npm 패키지 만들기와 유지보수 핵심

개요

npm 패키지 배포는 코드 재사용과 오픈소스 기여의 시작이다. 처음에는 절차가 복잡해 보이지만 차근차근 준비하면 안정적으로 운영할 수 있다. 이 글은 npm 패키지 배포 방법을 단계별로 정리하고, package.json 베스트프랙티스와 유지보수 포인트를 함께 설명한다.

사전 준비

필수 도구

• Node.js와 npm 최신 LTS 버전
• npm 계정 (npmjs.com)
• 버전 관리(Git)와 원격 저장소(GitHub 등)

권한과 접근

공개 패키지와 사설 패키지는 접근 방식이 다르다. 조직용 레지스트리를 사용하면 토큰 기반 접근 제어가 필요하다. 배포 전에 토큰을 발급하고 로컬에 안전하게 저장한다.

패키지 구조와 핵심 파일

권장 폴더 구조

• src/ 또는 lib/에 실제 코드 배치
• test/ 폴더에 단위 테스트
• README.md, LICENSE, .npmignore

package.json 베스트프랙티스

package.json은 패키지의 기본 명세다. 아래 항목을 꼼꼼히 관리하면 소비자가 혼란을 덜 느낀다.

• name: 고유하고 짧은 네임스페이스 사용
• version: SemVer(주.부.패치) 규칙 준수
• main: 번들 진입점 지정
• module / exports: 모듈 시스템별 진입점 설정
• files: 배포할 파일만 포함하여 패키지 용량 최소화
• scripts: build, test, lint, prepublishOnly 등 자동화 스크립트 등록
• engines: 지원하는 Node 버전 명시

간단한 Node 모듈 퍼블리시 예제

아래는 최소한의 패키지 초기화와 퍼블리시 절차 예시다. 이 과정은 로컬에서 테스트 후 실제 배포로 이어진다.

npm init -y
# package.json 내용을 수정
npm login
npm publish --access public

private 패키지는 --access public 옵션 없이 퍼블리시할 수 있다. 조직 레지스트리로 퍼블리시할 때는 레지스트리 URL을 지정한다.

package.json 예제

{
  "name": "my-awesome-package",
  "version": "1.0.0",
  "description": "간단한 유틸리티",
  "main": "lib/index.js",
  "files": ["lib"],
  "scripts": {
    "build": "babel src -d lib",
    "test": "jest",
    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": ["utility","example"],
  "author": "",
  "license": "MIT",
  "engines": {
    "node": ">=14"
  }
}

버전 관리와 배포 전략

Semantic Versioning

버전은 소비자에게 변경의 의미를 전달한다. 호환성 파괴 변경은 메이저 버전 증가, 기능 추가는 마이너, 버그 수정은 패치로 처리한다. 배포 전에는 changelog 또는 릴리스 노트를 반드시 작성한다.

릴리스 워크플로

• 기능 브랜치 → PR → 코드리뷰 → 메인 병합
• CI에서 빌드·테스트 통과 시 태그 생성과 퍼블리시 수행

테스트·CI 통합

자동화 파이프라인은 품질을 유지하는 핵심이다. GitHub Actions, GitLab CI 등을 사용해 다음을 자동화한다.

• lint, unit test, build
• 코드 커버리지 체크
• 태그 푸시 시 npm 퍼블리시 트리거

유지보수와 보안

의존성 관리

의존성은 주기적으로 점검한다. 취약점 스캐너(npm audit 등)를 사용해 리포트를 확인하고, 가능한 경우 최소 권한 패키지로 대체한다.

사용자 피드백과 호환성

이슈 템플릿을 마련해 버그 리포트와 호환성 문제를 체계적으로 수집한다. 중요한 변경은 마이그레이션 가이드를 제공한다.

패키지 폐기와 대체

더 이상 유지하지 않는 패키지는 deprecate 명령으로 알리고 대체 패키지 링크를 제공한다. 예시는 다음과 같다.

npm deprecate my-old-package@"*" "더 이상 유지되지 않음. 대체: new-package"

마무리

요약하면, npm 패키지 배포 방법은 준비, 명세 관리, 자동화, 유지보수의 연속이다. package.json 베스트프랙티스와 CI 통합, 버전 정책을 지키면 안정적이고 신뢰받는 패키지를 운영할 수 있다. Node 모듈 퍼블리시 예제와 절차를 따라 차근히 적용해보면 배포가 익숙해진다.