18편에서 packages/ui는 tsdown으로 dist에 번들과 선언 파일을 만들고, devExports 덕분에 개발 중에는 소스를, 배포 시에는 dist를 가리키는 exports를 갖추게 됐습니다. 이번 편은 실제로 npm에 올리기 전 마지막 단계, 즉 배포 필드를 확정하고 npm pack으로 결과물을 검증하는 절차를 다룹니다. 이 편에서는 실제로 배포하지 않습니다.

이 편에서 만드는 파일

bookshelf-ts/
└── packages/
    └── ui/
        └── package.json    ~ (version, description, license, files, publishConfig.access 확정)

개념 정리

스코프 패키지명 충돌 주의

@bookshelf/ui의 bookshelf는 이 과목에서 쓰는 예시 스코프입니다. npm의 스코프(@ 뒤 이름)는 실제로 소유한 npm 사용자명이거나, npm에 만들어 둔 조직 이름이어야 합니다. 다른 사람이 이미 쓰고 있는 스코프에는 배포할 수 없습니다. 실제로 배포하려면 다음을 먼저 확인합니다.

• npm view @bookshelf/ui 실행 결과가 404면 그 이름은 비어 있다는 뜻입니다. 다만 스코프 자체를 내가 소유했는지는 별개로 확인해야 합니다.
• 자신의 npm 계정 사용자명이 chulsoo92라면 @chulsoo92/ui처럼 개인 스코프를 쓰는 것이 가장 안전합니다.
• 스코프 없는 이름(bookshelf-ui처럼)은 전역에서 단 하나만 존재할 수 있어 충돌 가능성이 훨씬 큽니다. 실무에서는 거의 항상 스코프를 씁니다.

package.json 배포 필드

0.1.0처럼 주 버전이 0인 동안은 API가 아직 불안정하다는 뜻으로 통용됩니다. 실사용자에게 배포할 준비가 되면 1.0.0으로 올립니다.

workspace 프로토콜과 배포 도구의 관계

packages/ui의 dependencies에는 "@bookshelf/shared-types": "workspace:*"가 들어 있습니다. pnpm publish·pnpm pack은 패키징 직전에 이 문자열을 실제 설치 가능한 버전 범위로 자동 치환합니다. 반면 npm pack·npm publish는 pnpm 워크스페이스를 알지 못해 workspace:*를 그대로 tarball에 남깁니다. 이 상태로 배포하면, 모노레포 밖에서 설치하는 사람은 workspace:*를 해석하지 못해 설치가 실패합니다.

실습

// packages/ui/package.json (18편 이후 상태에 배포 필드 추가)
{
  "name": "@bookshelf/ui",
  "version": "0.1.0",
  "description": "bookshelf-ts 재사용 UI 컴포넌트",
  "license": "MIT",
  "type": "module",
  "files": ["dist"],
  "sideEffects": false,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "publishConfig": {
    "access": "public",
    "exports": {
      ".": {
        "types": "./dist/index.d.ts",
        "import": "./dist/index.js",
        "require": "./dist/index.cjs"
      }
    }
  },
  "peerDependencies": {
    "react": "^19.3.0",
    "react-dom": "^19.3.0"
  },
  "dependencies": {
    "@bookshelf/shared-types": "workspace:*"
  }
}

cd packages/ui
npm pack --dry-run

npm notice
npm notice 📦  @bookshelf/ui@0.1.0
npm notice === Tarball Contents ===
npm notice 1.2kB package.json
npm notice 0.4kB dist/index.d.ts
npm notice 0.3kB dist/index.d.cts
npm notice 2.1kB dist/index.js
npm notice 2.3kB dist/index.cjs
npm notice === Tarball Details ===
npm notice name: @bookshelf/ui
npm notice version: 0.1.0

pnpm pack --pack-destination /tmp

tar -xOf /tmp/bookshelf-ui-0.1.0.tgz package/package.json | grep shared-types

"@bookshelf/shared-types": "^0.1.0"

pnpm publish --access public --dry-run

확인

• npm pack --dry-run 결과에 dist/index.js, dist/index.cjs, dist/index.d.ts, dist/index.d.cts가 모두 보입니다.
• src 폴더나 tsdown.config.ts는 tarball 목록에 없습니다.
• pnpm pack으로 만든 tarball 안 package.json에서 workspace:*가 실제 버전으로 바뀐 것을 확인합니다.
• pnpm publish --access public --dry-run이 오류 없이 끝납니다.

직접 해보기

1. npm view react version을 실행해 실제 배포된 패키지 정보를 조회하는 형식을 확인하고, 아직 존재하지 않는 이름(npm view @bookshelf/ui)과 결과가 어떻게 다른지 비교해 보세요.
2. package.json의 version을 0.2.0으로 올려야 하는 변경(기존 컴포넌트의 동작은 그대로 두고 Pagination처럼 새 컴포넌트만 추가하는 경우)과 1.0.0으로 올려야 하는 변경(기존 BookCard의 props 이름을 바꾸는 경우)을 구분해 적어 보세요.

자주 하는 실수

확인 문제

참고 자료

• npm Docs — npm publish 
• pnpm — publish