# NPM: Git과 Tarball로 의존성 관리

- Author: @baealex
- Published: 2025-11-16
- Updated: 2025-11-16
- Source: http://blex.me/@baealex/npm-git%EA%B3%BC-tarball%EB%A1%9C-%EC%9D%98%EC%A1%B4%EC%84%B1-%EA%B4%80%EB%A6%AC
- Tags: 자바스크립트, 프론트엔드

---

NPM에 올려지는 사내 디자인 시스템이 있다. 이 디자인 시스템을 사용해서 프로젝트를 개발해야 했으나, 아무래도 수정하면서 작업이 필요할 것 같았다. 기본적으로 디자인 시스템을 정상적으로 운용하기 위해선 `개발` → `검토` → `문서화` → `배포` 프로세스를 모두 거쳐야 하는데다, NPM에 올려진 이후에나 패키지를 프로젝트로 가져올 수 있기 때문에 상당히 많은 시간을 소요하게 만든다.

이것에 대해서 고민하다가, 누군가 Git과 Tarball( `.tar` )을 이용해서 처리할 수 있겠다고 하셔서 해당 방법에 대해서 알게 되었다. Deno 같은 경우에는 NPM을 비롯해 여러가지 저장소를 호환하고 있는 걸 알고 있었는데…

```json
{
  "imports": {
    "@std/path": "jsr:@std/path@^1.0.8",
    "chalk": "npm:chalk@^5.3.0"
  }
}
```

Node에서 NPM 외 방법으로 의존성을 설치하는 방식이 가능한지 몰랐었다! 커스텀하게 저장소를 운용하는 방법이 있는 걸 얼추 알았지만, 설정이 비교적 복잡한 걸로 보였기에 모른척(?) 했다. 이 방식을 활용한다면 간단한 방식으로 패키지의 Beta 버전을 운용하거나 Private 유형으로도 활용할 수 있겠다.

### Git 저장소 설치

**케이스 1. 특정 브랜치, 태그, 커밋 지정 (** `#` **활용)**

방법은 `#` (해시) 기호를 쓰는 거였다.

```bash
# "feature/new-button" 브랜치의 최신 버전을 설치
npm install github:my-org/my-design-system#feature/new-button

# "v1.2.0-beta" 태그 버전을 설치
npm install github:my-org/my-design-system#v1.2.0-beta

# 특정 커밋 해시(hash)를 직접 지정
npm install github:my-org/my-design-system#a1b2c3d4e5f6
```

이렇게 설치하면 `package.json` 에 다음과 같이 기록이 남는다.

```json
"dependencies": {
  "my-design-system": "github:my-org/my-design-system#feature/new-button"
}
```

이제 `npm install` 을 실행하면, npm은 레지스트리가 아닌 GitHub의 해당 브랜치에서 코드를 직접 가져온다. 덕분에 불필요한 베타 버전을 난립시킬 필요가 없어졌다.

**케이스 2. 전체 Git URL 사용**

GitHub가 아니거나, SSH 인증이 필요한 프라이빗 저장소는 전체 Git URL을 쓰면 되었다.

```bash
# HTTPS
npm install git+https://github.com/my-org/my-design-system.git#feature/new-button

# SSH (키 설정이 되어 있어야 함)
npm install git+ssh://git@github.com:my-org/my-design-system.git#feature/new-button
```

> 주의할 점!

우선 깃에 올라간 패키지들은 대부분 dist 파일 같은 것들은 ignore 되어 있기 때문에 우리 패키지에 의존성으로 설치한다고 해서 바로 사용할 수 있는게 아니다. `prepare` 스크립트에 빌드하도록 해두어야 패키지를 설치하는 라이프 사이클에서 정상적으로 빌드가 된다.

```json
{
  "name": "my-design-system",
  "version": "1.0.0",
  "scripts": {
    "build": "vite build", // 또는 tsc, rollup 등...
    "prepare": "npm run build" // 👈 이게 Git 설치용
  }
}
```

> 그리고 문제점…

결국 이 방식은 사용하지 못했는데, 디자인 시스템이 모노레포 안에서 관리되기 해당 케이스에는 대응 불가…

### Tarball URL 설치

이건 간단하다 NPM에 올라가는 유형 그대로 빌드를 진행한 다음에 `.tar.gz` 압축해서 S3를 비롯해 그냥 이 세상 웹 서버 어딘가에 올려둔다. 그리고 그 URL을 `npm install` 에 사용하면 된다.

```bash
# 빌드 산출물(.tar.gz)을 직접 설치
npm install https://my.example.com/build/my-design-system-v1.2.0-beta.tar.gz
```

`package.json` 에는 해당 URL이 그대로 박힌다. 개인적으로는 아주 직관적인 방식인 듯?

```json
"dependencies": {
  "my-design-system": "https://my.example.com/build/my-design-system-v1.2.0-beta.tar.gz"
}
```

동료의 힌트 덕분에 궁금해서 찾아봤다가, 효율적으로 개발할 수 있는 유용한 방법을 알게 되었다.