Article

npm 패키지 배포: Node.js 라이브러리 공개하기

2019. 2. 8.

개요

오픈소스 Node.js 라이브러리를 만들었다면 npm 레지스트리에 배포하여 전 세계 개발자들과 공유할 수 있습니다. 이 가이드는 npm 패키지 배포의 전체 과정을 단계별로 설명합니다.

사전 준비

1. npm 계정 생성

npm 웹사이트에서 계정을 생성합니다. 이메일 주소와 사용자명(username)이 필요합니다.

2. Node.js 및 npm 설치

Node.js를 설치하면 npm도 함께 설치됩니다:

node -v
npm -v

3. 로컬 npm 계정 인증

터미널에서 npm 계정에 로그인합니다:

npm login

사용자명, 비밀번호, 이메일을 입력합니다. 로그인 상태는 ~/.npmrc 파일에 저장됩니다.

프로젝트 설정

package.json 작성

배포할 패키지의 package.json 파일을 준비합니다:

{
  "name": "@username/my-package",
  "version": "1.0.0",
  "description": "패키지 설명",
  "main": "index.js",
  "scripts": {
    "test": "jest",
    "build": "tsc"
  },
  "keywords": ["keyword1", "keyword2", "keyword3"],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-package.git"
  },
  "bugs": {
    "url": "https://github.com/username/my-package/issues"
  },
  "homepage": "https://github.com/username/my-package"
}

중요한 필드들:

README.md 작성

사용 방법과 예시를 포함한 README 파일을 준비합니다:

# My Package

패키지 설명

## 설치

\`\`\`bash
npm install my-package
\`\`\`

## 사용법

\`\`\`javascript
const myPackage = require('my-package');
myPackage.doSomething();
\`\`\`

## License

MIT

배포하기

1단계: 최종 확인

배포 전에 테스트와 빌드를 실행합니다:

npm test
npm run build

2단계: npm에 배포

npm publish

공개 패키지인 경우 --access public 플래그를 추가할 수 있습니다:

npm publish --access public

3단계: 배포 확인

배포가 완료되면 npm 웹사이트에서 패키지를 검색할 수 있습니다:

https://www.npmjs.com/package/your-package-name

버전 관리

시맨틱 버전(Semantic Versioning)을 따릅니다:

• MAJOR: 호환되지 않는 변경 (1.0.0 → 2.0.0)
• MINOR: 하위 호환 기능 추가 (1.0.0 → 1.1.0)
• PATCH: 버그 수정 (1.0.0 → 1.0.1)

버전 업데이트

# PATCH 버전 업데이트
npm version patch

# MINOR 버전 업데이트
npm version minor

# MAJOR 버전 업데이트
npm version major

이 명령어는 package.json의 버전을 자동으로 업데이트합니다.

업데이트된 패키지 배포

버전을 업데이트한 후 다시 배포합니다:

npm publish

스코프 패키지

개인 네임스페이스가 있는 패키지를 배포할 수 있습니다:

{
  "name": "@username/my-package"
}

배포 시 public으로 설정해야 합니다:

npm publish --access public

자주 하는 실수

1. 이름 중복: 이미 존재하는 패키지명 사용
2. 버전 다중 배포: 같은 버전을 두 번 배포 (버전을 올려야 함)
3. credentials 누출: .npmrc에 토큰 저장 안 함
4. 테스트 없이 배포: 배포 전 항상 테스트 실행
5. README 누락: 설치 및 사용 방법 설명 필수

도움말

패키지 관리 명령어들:

# 로컬 패키지 테스트
npm link

# 패키지 정보 확인
npm info package-name

# 사용자가 배포한 패키지 목록
npm packages

# 패키지 언퍼블리시 (배포 취소)
npm unpublish package-name@version

마치며

npm에 패키지를 배포하면 전 세계 개발자들이 여러분의 코드를 사용할 수 있습니다. 처음에는 복잡해 보이지만 몇 번 반복하면 프로세스를 익힐 수 있습니다. 좋은 문서와 테스트가 있는 패키지는 더 많은 사용자를 유치하므로 이 두 부분에 신경 써주세요.