[week17] 프로젝트 : 오픈소스 기반의 웹 파이프라인 구축 (7) - 05/07

Kyulee·2026년 5월 7일

TIL

목록 보기

83/93

이번 시간에는 직접 만든 오픈소스 프로젝트를 npm에 배포하는 전 과정을 진행했습니다. 코드를 깃허브에 올리는 것에서 한 발 더 나아가, 누구나 npm install 명령어 하나로 내 패키지를 설치할 수 있도록 만드는 과정입니다.

깃허브에 코드를 올리는 것만으로는 다른 개발자들이 내 프로젝트를 쉽게 사용하기 어렵습니다. npm(Node Package Manager) 에 배포하면 전 세계 누구든 간단한 명령어 하나로 내 패키지를 설치하고 사용할 수 있습니다.

npm 배포는 거창한 것이 아닙니다. 패키지 설정 파일을 잘 작성하고 몇 가지 절차를 따르면 누구나 자신만의 npm 패키지를 배포할 수 있습니다.

npm을 통해서 오픈소스를 배포 해보자 (1)

npm 계정 생성 및 로그인

npm에 패키지를 배포하려면 먼저 npmjs.com 에서 계정을 생성해야 합니다.

# 터미널에서 npm 로그인
npm login

# 로그인 확인
npm whoami

package.json 설정

npm 배포의 핵심은 package.json 을 올바르게 작성하는 것입니다.

{
  "name": "패키지명",
  "version": "1.0.0",
  "description": "패키지에 대한 간단한 설명",
  "main": "index.js",
  "scripts": {
    "test": "jest"
  },
  "keywords": ["검색에 활용될 키워드"],
  "author": "이름 <이메일>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/계정/레포지토리명"
  }
}

주요 필드를 정리하면 다음과 같습니다.

필드	설명
`name`	npm에서 유일해야 합니다. 이미 사용 중인 이름은 사용할 수 없습니다
`version`	시맨틱 버저닝(Semantic Versioning) 형식을 따릅니다
`main`	패키지의 진입점 파일을 지정합니다
`keywords`	npm 검색 시 노출되는 키워드입니다
`license`	오픈소스 라이선스를 명시합니다

시맨틱 버저닝 (Semantic Versioning)

npm 패키지의 버전은 MAJOR.MINOR.PATCH 형식을 따릅니다.

구분	변경 시점
MAJOR	기존 버전과 호환되지 않는 변경이 있을 때 올립니다
MINOR	하위 호환성을 유지하며 기능을 추가할 때 올립니다
PATCH	하위 호환성을 유지하며 버그를 수정할 때 올립니다

npm을 통해서 오픈소스를 배포 해보자 (2)

배포 전 확인 사항

실제로 배포하기 전에 어떤 파일이 패키지에 포함될지 미리 확인하는 것이 중요합니다.

# 배포될 파일 목록 미리 확인
npm pack --dry-run

불필요한 파일이 포함되지 않도록 package.json 의 files 필드를 활용합니다.

{
  "files": [
    "dist/",
    "index.js",
    "README.md"
  ]
}

npm 배포

모든 준비가 완료되면 아래 명령어 하나로 배포할 수 있습니다.

npm publish

배포가 완료되면 https://www.npmjs.com/package/패키지명 에서 내 패키지 페이지를 확인할 수 있습니다. 이제 전 세계 누구든 아래 명령어로 내 패키지를 설치할 수 있습니다.

npm install 패키지명

버전 업데이트 및 재배포

패키지를 수정하고 다시 배포할 때는 반드시 버전을 올려야 합니다. npm에서는 이미 배포된 버전과 동일한 버전으로 재배포할 수 없습니다.

# patch 버전 자동으로 올리기 (1.0.0 → 1.0.1)
npm version patch

# minor 버전 자동으로 올리기 (1.0.0 → 1.1.0)
npm version minor

# major 버전 자동으로 올리기 (1.0.0 → 2.0.0)
npm version major

# 버전 업데이트 후 재배포
npm publish

GitHub Actions로 배포 자동화

매번 수동으로 배포하는 대신, 깃허브에 태그를 Push할 때 자동으로 npm에 배포되도록 GitHub Actions를 설정할 수 있습니다.

# .github/workflows/publish.yml
name: Publish to npm

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'

      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}