회사 내 패키지 매니저, Yarn에서 pnpm으로

잘 돌아가던 프로젝트가 어느 날 갑자기 빨간 줄을 뿜어내며 빌드에 실패한 경험 다들 한 번쯤 있으실 겁니다. 코드는 단 한 줄도 건드린 적이 없는데 말이죠. 원인을 파악해 보면 십중팔구 새로 설치한 패키지와 기존 패키지 사이의 의존성 충돌이나 알 수 없는 버전 꼬임 문제였습니다.

 

오랜 기간 Yarn을 사용해 오면서 패키지 설치 속도 자체에는 큰 불만이 없었습니다. 하지만 프로젝트 덩치가 커지고 추가되는 라이브러리가 많아질수록 이런 의도치 않은 패키지 버전 충돌 버그를 겪는 빈도가 잦아졌습니다. 원인 모를 런타임 에러에 시달리다 결국 node_modules 폴더를 통째로 지우고 캐시를 날린 뒤 다시 설치하는 소모적인 작업에 점점 지쳐갔죠.

 

우리는 이 문제의 근본적인 원인이 기존 패키지 매니저들이 가진 느슨한 구조적 한계에 있다는 것을 깨달았습니다. 그리고 이 지긋지긋한 의존성 버그를 원천적으로 차단하기 위해 새로운 대안을 찾았고 그것이 바로 pnpm이었습니다. 단순한 기술 스택의 유행을 좇은 것이 아니라 개발 생산성과 프로젝트의 안정성을 되찾기 위한 생존 마이그레이션이었던 우리 팀의 pnpm 전환 경험을 공유해 보려 합니다.

 

왜 패키지 매니저를 바꿔야 할까요?

"잘 쓰고 있는 Yarn을 왜 굳이?"라는 생각이 먼저 드실 겁니다. 하지만 프로젝트 규모가 커지고 모노레포(Monorepo) 환경을 도입하면서 기존 패키지 매니저의 한계가 명확하게 드러나기 시작했습니다. 우리가 패키지 매니저를 바꿔야만 했던 가장 핵심적인 두 가지 이유는 다음과 같습니다.

• 유령 의존성(Phantom Dependencies)의 위험 npm이나 Yarn은 중복 설치를 막기 위해 패키지들을 node_modules 최상단으로 끌어올리는 호이스팅(Hoisting) 방식을 사용합니다. 문제는 이로 인해 package.json에 명시하지 않은 패키지라도 코드에서 마음대로 불러와 사용할 수 있게 된다는 점입니다. 당장은 에러가 안 나니 편할지 몰라도 이는 언제 터질지 모르는 시한폭탄과 같습니다. 내부적으로 의존하던 다른 패키지가 업데이트되거나 삭제되면서 몰래 사용하던 유령 의존성이 함께 사라지면 어느 날 갑자기 멀쩡하던 런타임 환경이나 빌드가 터져버리기 때문입니다.
• 모노레포 환경에서의 완벽한 패키지 버전 공유 여러 프로젝트가 하나의 저장소에 모여있는 모노레포에서는 동일한 패키지 버전을 일관되게 공유하고 관리하는 것이 매우 중요합니다. 기존 방식에서는 최상단으로 호이스팅이 되더라도 결국 엣지 케이스에서 각 하위 패키지마다 중복된 의존성이 설치되거나 버전이 미세하게 꼬이는 일들이 발생했습니다. 디스크 용량 낭비는 덤이었죠. 우리는 모노레포 내의 모든 프로젝트가 완벽하게 동일한 의존성을 바라보고 패키지 버전의 파편화를 원천적으로 차단할 수 있는 구조가 절실했습니다.

pnpm은 어떻게 다른가요?

pnpm은 이러한 문제들을 해결하기 위해 완전히 새로운 아키텍처를 도입했습니다.

1. 엄격한 디렉토리 구조 (Strictness): pnpm의 node_modules 구조는 기존의 평탄화(flattening)된 구조와 다릅니다. 프로젝트의 package.json에 직접 명시하지 않은 패키지는 node_modules 최상위에 노출되지 않습니다. 이를 통해 개발자가 의도치 않은 패키지를 사용하는 유령 의존성 문제를 근본적으로 차단합니다.
2. 글로벌 스토어와 하드 링크 (Hard Links): pnpm은 패키지를 매번 프로젝트에 복사하지 않고 단일 글로벌 스토어에 한 번만 저장한 뒤 하드 링크를 통해 참조합니다. 모노레포 환경에서 수십 개의 패키지가 동일한 의존성을 필요로 하더라도 디스크에는 단 한 번만 저장되므로 공간을 획기적으로 절약하고 일관된 버전을 확실하게 공유할 수 있습니다.
3. 심볼릭 링크 (Symbolic Links): pnpm은 하드 링크를 사용하여 스토어를 관리하는 동시에 프로젝트 내의 복잡한 의존성 관계는 심볼릭 링크를 통해 영리하게 풀어냅니다. 패키지 간의 관계를 명확하게 유지하면서도 엄격한 구조를 가져갈 수 있는 비결입니다.

 

Yarn과 pnpm 장단점 비교

이제 본격적으로 Yarn과 pnpm을 비교해 보겠습니다.

Yarn

구분	장점	단점
장점	안정적인 생태계와 풍부한 레퍼런스	설치 속도가 pnpm에 비해 상대적으로 느림
	대규모 커뮤니티 지원	호이스팅으로 인한 유령 의존성 문제 발생
	익숙한 Workspaces 환경	중복 설치로 인한 디스크 공간 낭비
	Plug'n'Play (v2 이상)를 통한 성능 향상 시도	PnP 모드 적용 시 기존 생태계와 호환성 이슈 발생 빈번

 

pnpm

구분	장점	단점
장점	유령 의존성 완벽 차단	초기 도입 시 일부 패키지와 호환성 문제 발생 가능
	하드 링크를 통한 압도적인 디스크 공간 효율	기존 평탄화 구조에 익숙한 팀원들의 학습 비용
	모노레포에서의 확실한 버전 일치 및 관리	CI/CD 환경에서 별도의 글로벌 스토어 캐싱 세팅 필요
	Yarn 대비 훨씬 빠른 패키지 설치 속도	생태계가 Yarn에 비해 상대적으로 작음

우리 팀의 전환 경험

우리 팀 역시 여러 개의 서비스가 결합된 모노레포를 운영하면서 유령 의존성으로 인한 빌드 실패를 여러 번 겪었습니다. 로컬에서는 잘 되는데 CI 서버에서만 터지는 알 수 없는 에러를 추적해 보면 십중팔구 유령 의존성 문제였죠.

 

pnpm 전환이 처음부터 순탄했던 것은 아닙니다. 기존에 알게 모르게 유령 의존성을 사용하고 있던 코드나 호이스팅 구조에 강하게 결합된 일부 서드파티 라이브러리들이 pnpm의 엄격한 구조에서 동작하지 않았습니다. 의존성을 명시적으로 다시 잡아주고 .pnpmfile.cjs 등을 활용해 예외 처리를 해주는 며칠간의 진통이 있었습니다.

 

전환을 완료한 후의 결과는

• 빌드 안정성: 원인 불명의 빌드 에러가 사라졌습니다. 로컬과 CI 환경의 동작이 완벽하게 일치하게 되었습니다.
• 디스크 공간: 모노레포 전체의 node_modules 용량이 극적으로 감소했습니다.
• 설치 속도: CI 파이프라인에서 의존성을 설치하는 시간이 눈에 띄게 단축되어 전체 배포 프로세스가 훨씬 쾌적해졌습니다.