npm 패키지 관리 실전 가이드

npm은 JavaScript 생태계의 핵심 도구입니다. 패키지 설치부터 버전 관리, 스크립트 실행까지 제대로 활용하는 방법을 알아봅니다.

package.json 이해하기

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "프로젝트 설명",
  "main": "dist/index.js",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint .",
    "test": "jest"
  },
  "dependencies": {
    "react": "^18.2.0",
    "next": "^14.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "eslint": "^8.0.0"
  }
}

dependencies vs devDependencies

# dependencies - 프로덕션에 필요한 패키지
npm install react

# devDependencies - 개발에만 필요한 패키지
npm install -D typescript

프로덕션 빌드 시 devDependencies는 설치되지 않습니다.

버전 표기법

1.2.3
│ │ │
│ │ └── Patch: 버그 수정 (하위 호환)
│ └──── Minor: 기능 추가 (하위 호환)
└────── Major: 큰 변경 (하위 호환 안 됨)

버전 범위 지정

{
  "dependencies": {
    "exact": "1.2.3",       // 정확히 1.2.3
    "caret": "^1.2.3",      // 1.x.x (1.2.3 이상, 2.0.0 미만)
    "tilde": "~1.2.3",      // 1.2.x (1.2.3 이상, 1.3.0 미만)
    "range": ">=1.0.0 <2.0.0",
    "latest": "*"           // 최신 버전 (위험)
  }
}

^(캐럿)이 가장 많이 사용됩니다. minor와 patch 업데이트를 자동으로 받습니다.

package-lock.json

정확한 의존성 버전을 고정합니다.

# package-lock.json을 기반으로 설치 (CI/CD에서 권장)
npm ci

# package.json을 기반으로 설치 (lock 파일 업데이트 가능)
npm install

package-lock.json은 반드시 버전 관리에 포함해야 합니다. 팀 전체가 동일한 버전을 사용하게 됩니다.

유용한 npm 명령어

# 패키지 정보 확인
npm info react

# 설치된 패키지 목록
npm list
npm list --depth=0  # 직접 의존성만

# 오래된 패키지 확인
npm outdated

# 패키지 업데이트
npm update           # minor/patch 업데이트
npx npm-check-updates -u  # major 포함 업데이트 (주의)

# 중복 패키지 정리
npm dedupe

# 캐시 정리
npm cache clean --force

# 전역 패키지 목록
npm list -g --depth=0

npm scripts 활용

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",

    "prebuild": "npm run clean",
    "postbuild": "npm run notify",

    "clean": "rm -rf .next",
    "notify": "echo Build complete!",

    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",

    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix",

    "format": "prettier --write .",

    "prepare": "husky install"
  }
}

pre/post 훅

prebuild는 build 전에, postbuild는 build 후에 자동 실행됩니다.

스크립트 조합

# 순차 실행
npm run lint && npm run test

# 병렬 실행
npm run lint & npm run test
# 또는 npm-run-all 사용
npx npm-run-all --parallel lint test

peerDependencies

라이브러리 개발 시 사용합니다. 호스트 프로젝트가 특정 패키지를 가져야 함을 명시합니다.

{
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

이 라이브러리를 사용하는 프로젝트는 react 18 버전을 설치해야 합니다.

.npmrc 설정

# 레지스트리 설정
registry=https://registry.npmjs.org/

# 특정 스코프의 레지스트리
@mycompany:registry=https://npm.mycompany.com/

# 저장 시 정확한 버전 사용
save-exact=true

# engine 불일치 시 에러
engine-strict=true

모노레포 관리

여러 패키지를 하나의 저장소에서 관리합니다.

{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

# 특정 워크스페이스에서 명령 실행
npm run build --workspace=packages/utils

# 모든 워크스페이스에서 실행
npm run build --workspaces

마무리

npm을 제대로 이해하면 프로젝트 관리가 훨씬 수월해집니다. package-lock.json 관리, 적절한 버전 범위 지정, npm scripts 활용이 핵심입니다.

의존성이 많아질수록 취약점과 버전 충돌 위험이 커집니다. 정기적으로 npm audit과 npm outdated를 실행하는 습관을 들이세요.