npm을 통한 오픈소스 배포

⭐ 아엔 Aen (개발자지망생)·2026년 1월 10일

npm 데브코스

데브코스

목록 보기

119/131

npm을 통한 오픈소스 배포, 한 번에 이해하기

내가 만든 유틸 함수나 컴포넌트를 매번 복붙하기 귀찮다면? 한 번 배포해두면 어디서든 npm install로 가져다 쓸 수 있다. 그게 바로 npm 패키지 배포다. 핵심부터 한 줄로 정리하면 이렇다.

npm 오픈소스 배포 = 내가 만든 코드를 npm 레지스트리에 올려서, 전 세계 누구나 npm install로 쓸 수 있게 공개하는 것

쉽게 비유하면

앱스토어에 앱 올리는 거랑 같음! 내가 만든 앱(패키지)을 앱스토어(npm 레지스트리)에 등록해두면, 다른 사람들이 "설치" 버튼(npm install) 누르면 바로 받아서 쓸 수 있다.

앱스토어 = npm 레지스트리 (npmjs.com)
앱 = 내가 만든 패키지
설치 버튼 = npm install 패키지명
업데이트 = npm publish (새 버전 올리기)

근데 앱스토어랑 다른 점이 있다면, npm은 심사가 없음. 계정 만들고 명령어 하나면 바로 전 세계에 배포된다. 그만큼 책임감도 따라오는 것 같음!

자세히

배포 전 준비물

1. npm 계정

npmjs.com에서 가입. 무료다.

2. package.json 핵심 필드

패키지의 신분증 같은 파일이다. 배포할 때 이 필드들이 특히 중요하다.

{
  "name": "@내아이디/패키지이름",
  "version": "1.0.0",
  "description": "패키지 설명",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "license": "MIT",
  "keywords": ["검색에 걸릴 키워드"],
  "repository": {
    "type": "git",
    "url": "https://github.com/내아이디/패키지이름"
  }
}

name — 패키지 이름. @아이디/이름 형태는 스코프드 패키지라고 해서 내 이름으로 네임스페이스를 만드는 것
version — 버전. 올릴 때마다 올려야 함. 같은 버전으론 재배포 불가
main — 패키지 진입점. 빌드된 파일 경로
files — npm에 올라갈 폴더/파일 목록. 소스 말고 빌드 결과물만 올리는 게 일반적

3. 버전 규칙 — 시맨틱 버저닝 (SemVer)

버전 숫자 1.2.3은 그냥 숫자가 아니다. 정해진 약속이 있다.

1  .  2  .  3
↑      ↑     ↑
Major  Minor  Patch

Patch (1.0.0 → 1.0.1): 버그 수정
Minor (1.0.0 → 1.1.0): 하위 호환되는 새 기능 추가
Major (1.0.0 → 2.0.0): 기존 코드 깨지는 큰 변경 (Breaking Change)

npm install react@^18.0.0 할 때 ^ 표시가 "Major 버전만 같으면 Minor·Patch는 최신으로 받아도 됨"이라는 뜻인데, 이게 SemVer 약속 기반이다!

배포 흐름

1. npm login          # npmjs.com 계정 로그인
2. 코드 작성 & 빌드   # TypeScript면 컴파일해서 dist/ 생성
3. npm publish        # 배포!
   (스코프드 패키지면 npm publish --access public)
4. 업데이트할 때:
   npm version patch  # 버전 자동으로 올리고
   npm publish        # 재배포

README가 진짜 중요한 이유

npmjs.com 패키지 페이지에 README.md가 그대로 노출된다. 설치 방법, 사용 예제, API 문서가 없으면 아무도 안 씀. 오픈소스는 코드만큼 문서가 절반인 것 같음!

.npmignore vs files 필드

올리지 말아야 할 것들(소스 코드, 테스트 파일, 설정 파일)을 제외하는 방법 두 가지다.

files 필드에 올릴 것만 명시 (권장)
.npmignore에 안 올릴 것 명시

files 필드 쓰는 게 더 명확하고 실수가 없어서 요즘은 이쪽을 많이 씀 같음!

실사용 예

시나리오: 날짜 포맷 유틸 함수 배포

여러 프로젝트에서 formatDate() 함수를 매번 복붙한다면? 한 번 패키지로 만들어 올려두면 끝이다.

# 1. 배포
npm login
npm publish --access public

# 2. 다른 프로젝트에서 설치
npm install @내아이디/date-utils

# 3. 사용
import { formatDate } from "@내아이디/date-utils"

자동화 — GitHub Actions로 배포 자동화

태그 푸시하면 자동으로 npm에 배포되게 할 수 있다. CI/CD 파이프라인이랑 연결하는 거다.

# .github/workflows/publish.yml
on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

git tag v1.0.1 && git push --tags 하면 자동으로 빌드 → 배포까지 이어진다 같음!

한 방 정리

구분	내용
한 줄 정의	내 코드를 npm에 올려서 누구나 설치할 수 있게 공개
비유	앱스토어에 앱 올리기
핵심 파일	package.json (name·version·main·files)
버전 규칙	SemVer — Patch·Minor·Major
배포 명령어	`npm publish --access public`
자동화	GitHub Actions + NPM_TOKEN