npm 게시와 시맨틱 버전 관리

게시하기 전에 항상 npm publish --dry-run을 실행합니다. 이 명령은 실제로 아무것도 업로드하지 않고 게시를 시뮬레이션하여, 정확히 어떤 파일이 포함되는지, 각 파일의 크기와 패키지 압축 파일의 내용이 무엇인지 보여 줍니다. 원본 파일을 실수로 포함하거나 dist 디렉터리를 빠뜨리는 등의 흔한 실수를 찾아낼 수 있습니다.

files 필드를 사용하여 package.json에서 게시할 항목을 제어합니다: "files": ["dist", "README.md"]. 이 허용 목록 방식은 .npmignore보다 안전합니다. .npmignore는 차단 목록 방식이므로, 민감한 파일을 목록에 추가하는 것을 잊으면 해당 파일이 유출될 수 있습니다. 항상 dist, 타입 선언 및 문서를 포함합니다. src, tests 또는 node_modules는 절대 포함하지 않습니다.

npm 패키지는 시맨틱 버전 관리에 따라 버전을 지정합니다: MAJOR.MINOR.PATCH. 호환성을 깨뜨리는 변경 사항(속성 제거, API 서명 변경)에는 MAJOR를 증가시킵니다. 이전 버전과 호환되는 새 기능(새 컴포넌트, 새로운 선택적 속성)에는 MINOR를 증가시킵니다. 이전 버전과 호환되는 버그 수정에는 PATCH를 증가시킵니다. 0.x.x 버전은 아직 안정화되기 전 단계로 간주되며, 어떤 부분이든 변경되어 호환성이 깨질 수 있습니다.

사전 출시 식별자는 해당 버전이 아직 프로덕션에 사용할 준비가 되지 않았음을 나타냅니다. 1.0.0-alpha.1은 초기 실험용 빌드에, 1.0.0-beta.2는 기능은 완성되었지만 버그가 있을 수 있는 버전에, 1.0.0-rc.1(출시 후보)은 최종 테스트를 진행할 준비가 된 버전에 사용합니다. 사전 출시 버전은 npm publish --tag beta로 게시하여 기본 설치 버전이 되지 않도록 합니다.

Changesets는 컴포넌트 라이브러리에서 패키지 버전과 변경 기록을 관리할 때 사용하는 표준 도구입니다. 작업 흐름은 다음과 같습니다. 기여자는 yarn changeset add를 실행하여 변경된 내용과 변경 유형(major/minor/patch)을 기록합니다. CI는 yarn changeset version을 실행하여 패키지 버전을 증가시킵니다. 게시 단계에서는 yarn changeset publish를 실행하여 npm에 게시합니다.

Changesets는 기여자가 커밋한 변경 기록 파일을 바탕으로 CHANGELOG.md를 자동으로 생성하고 관리합니다. 각 항목에는 버전 번호, 출시 날짜 및 변경 사항 설명이 포함됩니다. 따라서 변경 기록을 수동으로 관리하지 않아도 모든 버전의 내용을 사람이 읽기 쉬운 형태로 기록할 수 있습니다.

semantic-release는 규약에 따른 커밋 메시지에서 다음 버전을 결정하는 완전 자동화 버전 관리 도구입니다(feat: → minor, fix: → patch, BREAKING CHANGE: → major). 버전을 증가시키고 변경 기록을 생성한 다음 npm에 게시하는 모든 작업이 main에 병합될 때 CI에 의해 실행됩니다. 수동으로 버전을 관리할 필요가 전혀 없습니다.

범위가 지정되지 않은 패키지(my-component)는 항상 공개됩니다. 범위가 지정된 패키지(@myorg/my-component)는 기본적으로 제한됨(비공개) 상태이므로, npm publish --access public을 사용하여 공개로 게시해야 합니다. 제한된 패키지를 게시하려면 npm 유료 계정이나 조직이 필요합니다. 처음 게시하기 전에 접근 권한 설정을 확인합니다.

npm 출처 증명을 사용하면 게시한 패키지를 특정 git 커밋에 검증 가능한 방식으로 연결할 수 있습니다. GitHub Actions에서 npm publish --provenance를 사용하여 활성화합니다. 사용자는 npm 레지스트리 페이지에 표시된 정확한 원본 커밋에서 설치한 패키지가 빌드되었는지 확인할 수 있습니다. 이를 통해 공급망 보안이 크게 향상됩니다.

특정 버전에 심각한 버그나 호환성을 깨뜨리는 변경 사항이 있다면 해당 버전의 사용을 중단하도록 표시합니다: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm은 해당 버전을 설치하는 모든 사용자에게 사용 중단 경고를 표시합니다. 이 작업은 버전을 삭제하지 않습니다. npm은 기본적으로 게시된 버전을 삭제하지 않으며, 사용자에게 업그레이드하도록 알리는 역할만 합니다.

범위가 지정된 패키지는 @scope/package-name 형식을 사용합니다. 범위는 일반적으로 npm 사용자 이름이나 조직 이름입니다. 범위가 지정된 패키지를 사용하면 누가 패키지를 관리하는지 명확하게 알 수 있고, 범위가 지정되지 않은 패키지와의 이름 충돌을 방지할 수 있습니다. 비공개 패키지와 조직에 속한 오픈 소스 패키지에는 범위가 지정된 패키지를 사용합니다.

npm publish --dry-run으로 게시될 내용을 미리 확인하고, files 필드로 게시할 항목을 제어합니다. 시맨틱 버전 관리에서는 호환성을 깨뜨리는 변경 사항에 MAJOR, 새 기능에 MINOR, 수정 사항에 PATCH를 사용합니다. 사전 출시 버전에는 -alpha/-beta/-rc 태그를 사용합니다. Changesets는 협업 라이브러리의 버전 관리와 CHANGELOG 생성을 자동화합니다. semantic-release는 규약에 따른 커밋을 바탕으로 이 과정을 자동화합니다. 공급망 보안을 위해 --provenance를 활성화합니다. 버그가 있는 버전은 npm deprecate로 사용을 중단하도록 표시합니다.