자바스크립트 패키지 매니저: npm, yarn, pnpm

패키지 매니저란

패키지 매니저는 프로젝트에 필요한 외부 패키지를 설치·업데이트·삭제하고, 패키지끼리의 의존성을 관리하는 도구다. 설치 한 번이 컴퓨터와 앱에 무엇을 바꾸는지는 npm install이 하는 일에 있다. 자바스크립트 프로젝트는 수십~수백 개의 패키지에 기대기 때문에, 어떤 버전이 설치됐는지 기록하고 누구의 컴퓨터에서든 같은 의존성을 재현하는 일이 중요하다.

lock 파일은 package.json의 범위(^4.0.0, ^4.5.0)를 실제 버전 하나(4.6.3)와 내려받을 주소·해시로 풀어 둔 기록이다. 범위가 겹치면 한 버전으로 합쳐 적는다. 매니저가 자동으로 고치는 파일이라 손으로 편집하지 않는다. lock 파일이 없으면 설치할 때마다 범위 안의 최신 버전을 새로 고른다. 그래서 어떤 의존성이 MINOR 업데이트에 깨지는 변경을 실수로 넣으면(유의적 버전을 어기면) 로컬에서 통과한 코드가 CI에서만 깨진다. lock 파일은 「언제 어디서 설치해도 같은 node_modules」를 보장해 이 비결정성을 없앤다. 설치할 때는 최상위 프로젝트의 lock 파일만 쓰고, 의존 패키지 안에 든 lock 파일은 무시한다. 그래서 라이브러리 작성자도 개발 재현을 위해 lock 파일을 커밋하지만, 그것이 사용자 설치 버전을 고정하지는 않는다.

의존성 추가와 npm 스크립트

npm install axios date-fns     # dependencies: 실행 코드가 import하는 패키지
npm install -D vite eslint     # devDependencies: 빌드·검사·테스트에만 쓰는 도구
npx eslint .                   # 전역 설치 없이 프로젝트(또는 임시로 받은) 패키지의 명령 실행

• 의존성이 많으면 업데이트를 대화형으로 고른다. pnpm update -i --latest, yarn upgrade-interactive가 낡은 패키지 목록을 보여 주고 올릴 것만 체크하게 한다. npm은 npm outdated로 목록만 보여 주므로 npx npm-check-updates -i를 쓴다.
• node_modules 안의 파일은 직접 고치지 않는다. 다음 설치 때 덮어써진다. 폴더는 언제 지워도 npm install로 다시 만들 수 있다. 패키지를 꼭 고쳐야 하면 pnpm patch나 patch-package로 패치 파일을 남긴다.
• package.json의 scripts에 명령을 적어 두면 npm run dev처럼 실행한다. start·test는 run 없이 npm start·npm test로 줄여 쓴다. 스크립트 안에서는 node_modules/.bin의 명령을 경로 없이 쓸 수 있어 도구를 전역 설치할 필요가 없다. 훅·인자 전달·조합법은 npm 스크립트로 작업 자동화하기에 있다.
• 패키지를 고를 때는 관리 상태(최근 릴리스, 이슈 대응), 번들 크기, 필요한 함수만 가져올 수 있는지(import { format } from 'date-fns'처럼 named import로 트리 셰이킹되는지)를 본다. fetch, structuredClone, Intl 같은 내장 API로 충분하면 패키지를 더하지 않는다. 날짜 라이브러리의 예는 날짜 라이브러리에 있다.

왜 CDN이나 직접 내려받기 대신 매니저인가

package.json은 프로젝트 이름(name)·버전(version), 실행 명령(scripts), 의존성(dependencies, devDependencies)을 적는 매니페스트다. main·exports는 패키지를 라이브러리로 배포할 때 진입점을 알리는 필드라 앱 프로젝트에서는 보통 비워 둔다. npm init -y로 기본값 파일을 만든다.

npm install react가 "react": "^19.2.0"처럼 캐럿(^) 범위로 기록하는 것은 npm의 기본값이다. ^는 같은 MAJOR 안, ~는 같은 MINOR 안의 업데이트를 허용한다. 범위 규칙과 0.x의 예외는 유의적 버전에 있다.

세 가지 매니저 비교

런타임 Bun도 npm 호환 패키지 매니저(bun install, lock 파일 bun.lock)를 내장하고 있어 설치 속도를 앞세운 네 번째 선택지가 됐다.

pnpm의 node_modules는 package.json에 적지 않은 패키지에 접근할 수 없도록 엄격하게 구성된다. 다른 패키지의 의존성을 우연히 가져다 쓰는 "유령 의존성" 문제를 막아 주지만, 그런 패키지에 기대던 프로젝트는 옮길 때 오류가 날 수 있다.

어떤 것을 고를까

• 세 도구 모두 실무에서 쓰기에 충분히 안정적이다. 초기에는 yarn이 npm의 보안·속도 문제의 대안으로 꼽혔지만, npm도 lock 파일 도입 등으로 꾸준히 개선해 격차가 줄었다.
• 프로젝트 하나에는 매니저 하나만 쓴다. lock 파일이 두 종류 섞이면 팀원마다 다른 버전이 설치된다.
• 디스크를 많이 쓰는 모노레포나 패키지가 많은 프로젝트라면 pnpm의 이점이 커진다.
• 결국은 팀 컨벤션과 배포 환경 지원 여부를 보고, 필요하면 직접 설치 속도와 방식을 비교해 정한다.

매니저와 버전 고정: packageManager와 Corepack

package.json의 packageManager 필드("packageManager": "pnpm@10.x.x")에 프로젝트가 쓰는 매니저와 정확한 버전을 적는다. Corepack은 이 필드를 읽어 맞는 yarn·pnpm을 자동으로 내려받아 실행하는 도구다. Node.js 16.9~24에는 Corepack이 함께 배포됐지만 Node.js 25부터는 빠졌다. 필요하면 npm install -g corepack으로 따로 설치하고, CI·Docker 이미지에도 설치 단계를 넣는다.

Node.js 버전 고정: nvm과 .nvmrc

매니저보다 아래층인 Node.js 버전도 프로젝트마다 다르다. 시스템에 Node를 하나만 깔지 않고 버전 관리자로 여러 버전을 두고 바꿔 쓴다. 대표가 nvm(Node Version Manager, macOS·Linux 셸 스크립트)이고, 더 빠른 Rust 구현인 fnm, 여러 언어를 함께 다루는 mise·asdf도 같은 일을 한다. Windows는 별도 프로젝트인 nvm-windows를 쓴다.

nvm install --lts      # 최신 LTS 설치 (nvm install node 는 최신 Current)
nvm install 22         # 메이저 버전으로 설치
nvm use 22             # 이 셸에서 쓸 버전
nvm ls                 # 설치된 버전, nvm ls-remote 는 설치 가능한 버전
nvm alias default 22   # 새 셸의 기본값
echo "22" > .nvmrc     # 프로젝트 버전 기록 → 이 폴더에서 nvm use / nvm install

• 프로젝트 루트의 .nvmrc(fnm·mise도 읽는다)와 package.json의 engines.node에 버전을 적어 팀과 CI가 같은 Node를 쓰게 한다. GitHub Actions의 actions/setup-node도 node-version-file: .nvmrc로 읽는다.
• 운영에는 짝수 메이저의 LTS를 쓴다. 홀수 버전은 6개월만 지원된다.
• 버전 관리자로 깐 Node에서는 npm install -g가 그 버전 폴더 안에 들어가 sudo가 필요 없다. 대신 Node 버전을 바꾸면 전역 패키지도 따로다. 도구는 전역 설치보다 devDependencies + npx를 쓴다.

공급망 보안 기본값

npm 패키지 탈취·악성 배포 사고가 잦아지면서, 설치 중에 의존성의 postinstall 같은 라이프사이클 스크립트를 실행하지 않는 것이 기본값이 되고 있다.

lock 파일을 커밋하고 CI에서는 npm ci·pnpm install --frozen-lockfile처럼 lock 파일을 바꾸지 않는 명령을 쓰는 것도 같은 맥락이다.

트러블슈팅: npm ERR! code EINTEGRITY

Vercel 같은 배포 환경에서 npm install 단계가 다음처럼 실패할 때가 있다.

npm ERR! code EINTEGRITY
npm ERR! sha512-... integrity checksum failed when using sha512: wanted sha512-... but got sha512-...
Error: Command "npm install" exited with 1

Vercel이라면 프로젝트 설정의 Install Command를 다음처럼 덮어쓴다.

npm cache verify && npm cache clean --force && rm -rf package-lock.json && npm install

다만 package-lock.json을 지우면 버전 범위 안에서 새 버전이 설치될 수 있다. 급한 불을 끈 뒤에는 로컬에서 lock 파일을 다시 생성해 커밋하고 Install Command를 원래대로 돌려 두는 편이 안전하다.

정리

• 패키지 매니저는 의존성 설치와 버전 재현을 맡고, 그 핵심은 lock 파일이다.
• 실행 코드는 dependencies, 도구는 devDependencies. 도구는 전역 설치 대신 npm 스크립트와 npx로 돌린다.
• npm은 기본 포함과 생태계, yarn은 PnP 같은 새 설치 방식, pnpm은 디스크 효율과 엄격한 의존성, Bun은 속도가 강점이다.
• 매니저 버전은 packageManager 필드로 고정한다. Corepack은 Node.js 25부터 따로 설치한다.
• 한 프로젝트에는 한 매니저, lock 파일은 커밋한다.
• EINTEGRITY는 해시 불일치다. 캐시를 비우고 lock 파일을 다시 만든다.

관련 노트: npm install이 하는 일, 작은 모듈 철학과 npm 의존성, 번들러의 역사와 Vite, ESLint와 Prettier 설정, CI/CD, Windows 개발 환경