npm publish(CLI 패키지 배포)

1. package.json 필수 항목 세팅

npm에 배포하기 전에 package.json을 제대로 채워야 함. 빠뜨리면 npm 페이지가 허전하거나 검색에 안 잡힘.

{
  "name": "패키지명",
  "version": "0.1.0-beta.1",
  "description": "패키지 설명 (영어 권장)",
  "license": "MIT",
  "author": "깃헙유저명",
  "homepage": "https://github.com/유저명/레포명",
  "repository": {
    "type": "git",
    "url": "https://github.com/유저명/레포명.git"
  },
  "bugs": {
    "url": "https://github.com/유저명/레포명/issues"
  },
  "keywords": ["키워드1", "키워드2"],
  "files": ["dist/", "prompts/"],
  "bin": {
    "명령어명": "./dist/index.js"
  }
}

각 항목 설명:

• keywords — npm 검색 노출에 직결됨. 핵심 키워드 10개 이내로
• files — npm에 올라갈 파일/디렉토리만 명시. src/, node_modules/ 등은 제외
• bin — CLI 툴이라면 필수. 명령어명으로 터미널에서 실행 가능해짐

---

2. 버전 관리 (semver)

npm은 major.minor.patch 형식의 semver를 따름.

버전 올리는 시점	예시
patch — 버그 수정	0.1.0 → 0.1.1
minor — 기능 추가 (하위 호환)	0.1.0 → 0.2.0
major — 하위 호환 깨지는 변경	0.1.0 → 1.0.0

베타 배포 시엔 프리릴리즈 태그를 붙임:

0.1.0-beta.1
0.1.0-beta.2

---

3. prepublishOnly 스크립트 추가

TypeScript 프로젝트라면 publish 전에 빌드가 자동으로 돌도록 설정해두는 게 좋음. 빌드 까먹고 올리는 실수 방지.

"scripts": {
  "build": "tsc",
  "prepublishOnly": "npm run build"
}

---

4. .gitignore vs npm 배포 파일

.gitignore와 npm에 올라가는 파일은 별개임.

• GitHub에 올라가는 것 → git이 추적하는 파일 전체
• npm에 올라가는 것 → package.json의 files 필드에 명시한 것만

즉 src/를 GitHub에 공개하면서 npm엔 dist/만 올리는 구조가 가능함.

배포 전 확인:

npm pack --dry-run  # 실제로 올라갈 파일 목록 미리 확인

---

5. npm 계정 및 2FA 설정

npm login  # 로그인
npm whoami  # 로그인 상태 확인

2FA가 활성화된 계정이라면 publish 시 인증이 필요함. npmjs.com에서 Granular Access Token을 발급받아 사용하면 편함:

1. npmjs.com → 프로필 → Access Tokens
2. Generate New Token → Granular Access Token
3. bypass two-factor authentication 체크
4. 토큰 복사

publish 시 토큰 사용:

npm publish --tag beta --//registry.npmjs.org/:_authToken=<토큰>

---

6. 베타 배포

--tag beta를 붙이면 @beta 없이는 설치가 안 됨. 일반 사용자가 실수로 불안정한 버전을 설치하는 걸 방지.

npm publish --tag beta

설치:

npm install -g 패키지명@beta   # beta 태그
npm install -g 패키지명        # stable (태그 없음)

---

7. 패치 배포 (업데이트)

코드 수정 후 배포할 때는 버전을 올리고 다시 publish:

# package.json version 수정 후
npm publish --tag beta

같은 버전으로 재배포는 불가. 반드시 버전을 올려야 함.

---

8. 배포 취소

• 72시간 이내 → npm unpublish 패키지명@버전 으로 완전 삭제 가능
• 72시간 이후 → 삭제 불가, deprecated 처리만 가능

npm deprecate 패키지명@버전 "This version is no longer maintained."

---

마치며

처음엔 복잡해 보이지만 한 번 해보면 별거 없음. 핵심은:
1. package.json 꼼꼼히 채우기
2. files 필드로 올라갈 파일 제어하기
3. 베타는 --tag beta로 안전하게 배포