[트러블슈팅] NPM에서 PNPM으로

🧩 문제 상황

프로젝트를 초기에는 가장 보편적으로 사용되는 npm을 기본 패키지 매니저로 구성했었다.

또한, TypeScript, TailwindCSS, React Query 등 다양한 라이브러리를 함께 사용하며 개발을 이어갔다.

 

그러나 기능이 점차 확장되고 의존성이 많아질수록, 아래와 같은 문제에 반복적으로 직면하게 되었다.

 

👾 npm install 실행 시, 20초 이상 소요되는 느린 설치 속도

👾 node_modules 디렉토리의 지속적인 용량 증가

👾 의존성 간 충돌로 인한 npm install 실패 및 Cannot find module 오류 발생

👾 CI 환경에서의 빌드 시간 증가 및 불안정한 캐시 처리

 

이러한 문제들은 단순한 불편함을 넘어서

개발 속도 저하로 이어졌다.

 

 

---

🔍 원인 분석

처음에는 단순히 "사용하는 라이브러리가 많아서 그런가 보다" 라고 생각했지만,

문제의 본질을 정확히 파악하기 위해 직접 구조를 분석하고 원인을 추적해보았다.

 

 

1️⃣ node_modules 구조의 비효율성

npm은 모든 의존성을 디렉토리 구조로 복제하여 설치하는데,

이 과정에서 중복된 버전의 패키지들이 중첩된 구조로 설치되며,

결과적으로 비정상적으로 깊은 트리 구조와 디스크 낭비가 발생한다.

 

2️⃣ 디스크 기반 탐색 방식의 한계

프로젝트에서 라이브러리를 import나 require 할 때,

패키지 매니저는 node_modules 디렉토리를 상위까지 순회하며 해당 모듈을 찾기 때문에

이 과정은 파일 시스템에 대한 반복적인 접근을 발생시키며,

결과적으로 디스크 I/O 비용을 증가하고, 설치 속도가 저하되는 주요 원인이 된다.

 

3️⃣ 캐시 및 재설치의 비효율성

package-lock.json이 존재하더라도, 작은 변경이 생기면 전부 다시 다운로드해야 하며,

CI에서는 종종 lock 파일 충돌 혹은 캐시 누락으로 인해 npm install이 실패하기도 한다.

 

 

---

🔁 해결 시도: PNPM으로 변경

문제 해결을 위해 다양한 대안을 검토한 끝에 pnpm을 도입하기로 결정했다.

 

pnpm은 하드링크 기반으로 패키지를 설치하기에

디스크 공간을 효율적으로 사용하고,

설치 속도를 비약적으로 향상시켜주는 방식이기 때문이다.

 

마이그레이션 과정은 간단했다.

👉🏻 기존의 package-lock.json  및 node_moduels 제거

👉🏻 pnpm install 명령어로 package.json을 pnpm-lock.yaml로 변환

👉🏻 CI 환경에서는 actions/setup-pnpm 액션 추가 및 캐시 전략 수정

 

전체 마이그레이션은 큰 변경 없이 비교적 간단하게 진행되었으며,

기존 package.json 구조를 그대로 유지할 수 있어서

안정적으로 적용할 수 있었다.