툴링난이도 쉬움⏱ 30분~1시간
npm에서 pnpm으로 마이그레이션
npm→pnpm
요약: pnpm import로 기존 lock을 변환한 뒤 node_modules를 재설치하면 디스크 절약과 설치 속도 향상을 얻습니다. CI와 모노레포에서 특히 유리합니다.
왜 옮기나
- pnpm은 콘텐츠 주소 저장소로 패키지를 하드링크해 디스크와 설치 시간을 크게 절약합니다.
- 엄격한 의존성 격리로 유령 의존성(phantom dependency) 문제를 막습니다.
- 내장 workspace로 모노레포 관리가 깔끔합니다.
전제 — 현재 상태
npm + package-lock.json 사용.
마이그레이션 단계
1
pnpm 설치
corepack으로 활성화하거나 전역 설치합니다.
corepack enable pnpm
# 또는: npm install -g pnpm2
lock 변환
pnpm import가 package-lock.json을 읽어 pnpm-lock.yaml로 버전을 보존 변환합니다.
pnpm import3
재설치
기존 node_modules와 npm lock을 지우고 pnpm으로 설치합니다.
rm -rf node_modules package-lock.json
pnpm install4
CI·스크립트 교체
CI 캐시 키와 install 명령을 pnpm으로 바꾸고, npm run을 pnpm으로 교체합니다.
pnpm install --frozen-lockfile
pnpm run build⚠️ 막히는 케이스 · 함정
- 엄격 격리 때문에 유령 의존성에 의존하던 코드가 깨질 수 있습니다 — 빠진 패키지를 dependencies에 명시하세요.
- 일부 도구가 평면 node_modules를 가정하면 .npmrc의 node-linker=hoisted가 필요할 수 있습니다.
- Vercel 등 배포 플랫폼은 pnpm-lock.yaml을 감지하면 자동으로 pnpm을 씁니다.
✅ 검증: pnpm install 후 빌드·테스트·dev가 모두 통과하는지, CI가 frozen-lockfile로 재현되는지 확인합니다.
pnpmnpm패키지매니저모노레포corepack