[77일차]오픈소스 프로젝트의 완성: npm 배포 및 관리 가이드

개발한 라이브러리를 전 세계 개발자들과 공유하기 위한 마지막 단계는 패키지 매니저에 등록하는 것이다. JavaScript 생태계에서 가장 거대한 저장소인 npm(Node Package Manager)에 배포하는 방법과 주의사항을 정리한다.

1. 사전 준비: npm 계정 생성 및 인증

배포를 위해서는 npm 공식 사이트의 계정이 필요하다.

• 회원가입: npmjs.com에서 계정을 생성한다. 이때 입력한 이메일은 반드시 인증(Verify) 과정을 거쳐야 배포 권한이 부여된다.
• CLI 로그인: 터미널에서 다음 명령어를 입력하여 로컬 환경과 npm 계정을 연결한다.

  npm login

  명령어를 입력하면 웹 브라우저가 실행되며 인증을 진행하게 된다.

2. 프로젝트 설정 최적화

2.1 package.json 구성

package.json은 패키지의 명세서이다. npm 사이트에서 노출되는 정보들이 여기서 결정되므로 상세히 작성해야 한다.

{
  "name": "minidash-util",
  "version": "1.0.0",
  "description": "Lodash를 경량화한 JavaScript 유틸리티 라이브러리이다.",
  "main": "index.js",
  "type": "module",
  "keywords": ["modules", "util", "javascript"],
  "repository": {
    "type": "git",
    "url": "https://github.com/username/repo"
  },
  "author": "YourName",
  "license": "MIT"
}

• name: 유니크해야 한다. 이미 존재하는 이름은 사용할 수 없다.
• version: Semantic Versioning(SemVer) 규칙을 따른다.
• repository & homepage: 등록 시 npm 페이지 우측 하단에 링크가 생성되어 신뢰도를 높여준다.

2.2 .npmignore 활용

.gitignore가 Git 관리 제외 대상을 정한다면, .npmignore는 npm 배포 시 제외할 파일을 결정한다.

• 배포 시에는 소스 코드와 배포용 빌드 파일만 포함하는 것이 원칙이다.
• 테스트 코드(test/), 설정 파일(webpack.config.js), 로컬 로그 파일 등을 제외하여 패키지 용량을 최적화한다.

3. 패키지 배포 및 버전 관리

3.1 배포 실행

모든 설정이 완료되었다면 다음 명령어로 배포를 진행한다.

npm publish

만약 관리자 권한 문제가 발생한다면 sudo npm publish를 사용하거나 노드 버전 관리자(NVM)를 통해 권한 설정을 변경해야 한다.

3.2 버전 업데이트 (SemVer)

코드를 수정하고 다시 배포할 때는 반드시 버전을 올려야 한다.

• Patch (1.0.1): 버그 수정 시 사용 (npm version patch)
• Minor (1.1.0): 새로운 기능 추가 시 사용 (npm version minor)
• Major (2.0.0): 하위 호환성이 깨지는 변경 시 사용 (npm version major)

4. 배포 중 발생할 수 있는 주요 에러

4.1 E403: Forbidden (Forbidden)

배포하려는 패키지 이름이 이미 존재하거나, 매우 유사한 이름이 등록되어 스팸 방지 정책에 걸린 경우이다. 이름을 더 유니크하게 수정해야 한다.

4.2 E402: Payment Required

최근에는 @사용자이름/패키지명 형태의 Scoped Package를 많이 사용한다. 기본적으로 Scoped Package는 비공개(Private)로 설정되어 결제를 요구하게 된다. 무료로 공개 배포하려면 --access=public 옵션을 추가해야 한다.

npm publish --access=public

5. 배포 취소(Unpublish)와 책임감

잘못 배포된 버전은 npm unpublish로 삭제할 수 있으나, 오픈소스 생태계에서는 신중해야 한다.

• 취소 가능 조건: 배포 후 72시간 이내에는 자유롭게 취소가 가능하다.
• 72시간 경과 후: 해당 패키지를 의존성으로 사용하는 다른 프로젝트가 없어야 하며, 다운로드 수가 적어야 하는 등 조건이 매우 까다로워진다.
• 이유: 내가 삭제한 패키지 때문에 이를 사용하던 전 세계의 수많은 프로젝트가 빌드 에러를 일으킬 수 있기 때문이다.

6. 오픈소스 기여 매너

오픈소스 프로젝트에 기여하는 과정에서 가장 주의해야 할 점은 '의미 없는 기여'를 지양하는 것이다.

• 최근 express.js 등 유명 프로젝트에 단순 오타 수정이나 의미 없는 내용을 PR(Pull Request)로 보내는 이른바 'PR 테러'가 사회적 문제가 된 바 있다.
• 학습을 위한 연습은 반드시 본인의 테스트용 레포지토리나 전용 연습 공간(Sandbox)에서 진행해야 한다. 실제 운영 중인 프로젝트에 무분별한 요청을 보내는 것은 메인테이너의 시간을 뺏는 행위임을 명심해야 한다.