npm(Node Package Manager)은 서드파티 패키지(의존성)를 설치 및 관리하고 프로젝트 스크립트를 실행하는 Node의 기본 도구입니다. 두 개의 파일이 프로젝트를 정의합니다. package.json(매니페스트)과 package-lock.json(정확한 의존성 트리)입니다.
package.json — 프로젝트 매니페스트
json
이 파일은 메타데이터, 스크립트, 의존성을 기록합니다. ^4.18.0은 semver 범위입니다. ^는 호환 가능한 minor/patch 업데이트를 허용합니다(4.x.x은 되지만 5.0.0은 안 됨).
package.json says: express ^4.18.0 (a RANGE — could install 4.18.0 or 4.19.2...)
package-lock.json: express 4.18.2 (the EXACT version + every nested dependency)
lockfile은 설치된 모든 패키지(전이적 의존성 포함)의 정확한 버전을 고정합니다. 이를 통해 팀의 모든 구성원, CI, 프로덕션이 동일한 의존성 트리를 받게 보장하여 버전 차이로 인한 "내 컴퓨터에서는 되는데" 버그를 방지합니다.
npm install # install all deps from package.json (updates lockfile)
npm install express # add a dependency
npm install -D vitest # add a devDependency
npm ci # install EXACTLY from the lockfile (used in CI — fast, strict)
npm run dev # run a script defined in package.json
npm ci는(npm install과 달리) lockfile을 수정하지 않고 엄격하게 그대로 설치합니다. CI/프로덕션 재현성을 위한 올바른 명령어입니다.
✓ ALWAYS commit package-lock.json → reproducible installs across the team & CI
npm과 이 두 파일은 모든 Node 프로젝트의 기초입니다.
package.json(dependencies vs devDependencies, semver 범위, 스크립트)과 특히 lockfile이 존재하는 이유(전체 의존성 트리의 결정론적이고 재현 가능한 설치)를 이해하는 것은 필수적입니다. lockfile을 커밋하고 CI에서 npm ci를 사용하면 팀원이나 프로덕션이 다른 패키지 버전을 받아 생기는 미묘하고 디버깅하기 어려운 실패를 방지할 수 있습니다.