pnpm으로 갈아탄 뒤 알게 된 것들

npm → pnpm 전환을 몇 개 프로젝트에서 반복하며 배운 것들. 결론은 "새 프로젝트면 pnpm, 기존 프로젝트는 아픈 데 없으면 그대로"다.

왜 빠른가 — 하드링크 저장소

pnpm은 패키지를 전역 저장소(~/.pnpm-store)에 한 번만 풀고, 각 프로젝트의 node_modules에는 하드링크를 건다. 프로젝트 10개가 같은 react를 써도 디스크에는 1부다. 설치 속도와 디스크 사용량이 동시에 좋아진다.

진짜 차이 — 유령 의존성 차단

npm의 평탄화(flat) node_modules에서는 package.json에 없는 패키지도 import가 된다. 간접 의존성이 우연히 끌려와 있기 때문이다. 이게 유령 의존성이고, 간접 의존성이 사라지는 순간 빌드가 깨진다.

pnpm은 심링크 구조라 선언한 패키지만 접근 가능하다. 전환 직후 빌드가 깨진다면 대부분 이 유령들이 드러난 것 — 사실 버그를 미리 잡아 준 거다.

# 전환은 이게 전부
corepack enable
pnpm import   # package-lock.json → pnpm-lock.yaml
rm -rf node_modules package-lock.json
pnpm install

주의할 것들

• postinstall 의존 패키지: pnpm은 기본적으로 의존성의 빌드 스크립트를 차단한다(보안). sharp, esbuild 같은 네이티브 패키지는 pnpm.onlyBuiltDependencies에 명시 허용
• Docker: corepack enable을 이미지에 넣고, store를 캐시 마운트하면 npm ci보다 빨라진다
• 일부 도구의 호환성: 심링크를 못 따라가는 낡은 도구가 아직 가끔 있다. node-linker=hoisted로 탈출구는 있지만, 그 순간 pnpm의 장점 절반이 사라진다

정리

속도 때문에 갈아탔다가 유령 의존성 차단 때문에 남게 된다. 모노레포(workspace)까지 갈 계획이 있다면 더더욱 pnpm이 기본값이다.