01. pnpm 멘탈 모델

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 💾 npm의 고질적인 두 가지 문제
• 🏪 content-addressable store
• 🔗 하드링크 vs 심링크
• 🚀 pnpm 설치 3단계 파이프라인
• ⚖️ npm vs pnpm 한눈에 비교

8. pnpm 설치 & 프로젝트 첫 세팅
9. 총정리
10. 마무리 퀴즈
11. 영철이의 퇴근 일기
12. 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 약 25분(전체) / 핵심 파트만: 12분

🗺️ 이 문서의 흐름

[npm의 문제 인식] → [content-addressable store 원리] → [하드링크/심링크 메커니즘] → [설치 파이프라인] → [첫 세팅]

🎯 이 문서를 다 읽으면 할 수 있는 것

• npm과 pnpm의 근본적인 저장 방식 차이를 설명할 수 있다
• content-addressable store 가 왜 디스크를 절약하는지 이해할 수 있다
• 하드링크와 심링크의 역할 차이를 구분할 수 있다
• pnpm 을 설치하고 Next.js 프로젝트에 첫 세팅을 할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "영호 님, 저 요즘 프로젝트 3개를 동시에 작업 중인데요... SSD 용량이 자꾸 줄어들어요. node_modules 가 각 프로젝트마다 수백 MB 씩 먹는 거 아닌가요? 그리고 npm install 할 때마다 너무 오래 걸려서 점심 먹고 와도 아직도 돌아가고 있을 때가 있거든요. pnpm 이 빠르다는 말은 들어봤는데 그냥 npm 이랑 명령어만 비슷한 거 아닌가요?"
• 🦁 영호 ( 리드 ): "영철 님, npm 은 프로젝트마다 node_modules 에 패키지 파일을 복사 해요. 프로젝트가 10개면 react 도 10번 복사되는 거죠. pnpm 은 달라요 — 파일을 딱 한 번 저장하고 하드링크로 연결해요. 파일이 복사되는 게 아니라 '동일 파일을 가리키는 포인터' 를 추가하는 거라서 디스크 공간이 늘어나지 않아요. 설치 속도도 저장된 캐시에서 하드링크만 생성하면 되니까 훨씬 빠르고요."

🤔 왜 알아야 하는가

영수네 커뮤니티 팀의 어느 월요일 아침

영철이가 출근해서 노트북을 열었더니 알림이 떴다.

"디스크 공간 부족: 남은 공간 2.3GB"

당황해서 용량을 확인해 보니 홈 디렉토리에 projects/ 폴더만 22GB 를 먹고 있었다. 프로젝트 폴더 안을 들여다봤다.

projects/
├── youngsu-community/node_modules/   (487MB)
├── youngsu-admin/node_modules/       (312MB)
├── youngsu-landing/node_modules/     (298MB)
├── personal-blog/node_modules/       (445MB)
└── side-project/node_modules/        (391MB)

합치면 거의 2GB 가 node_modules 다. 그리고 각 프로젝트 안을 들여다보면 react@18, typescript, eslint 가 거의 동일한 버전 으로 다섯 번씩 복사되어 있다.

이것이 npm 의 근본적인 문제이고, pnpm 이 탄생한 이유다.

💾 npm의 고질적인 두 가지 문제

문제 1: 디스크 공간 낭비 (중복 복사)

npm 은 node_modules 를 프로젝트별로 독립적으로 복사 한다.

프로젝트 A/node_modules/react/  → react 파일 전체 복사 (1.2MB)
프로젝트 B/node_modules/react/  → react 파일 전체 복사 (1.2MB) ← 완전히 동일!
프로젝트 C/node_modules/react/  → react 파일 전체 복사 (1.2MB) ← 또 동일!

버전이 같은 패키지도 매번 새로 복사한다. 100개 프로젝트에서 lodash@4.17.21 을 쓴다면, 디스크 어딘가에 lodash 가 100개 존재한다.

문제 2: 팬텀 의존성 (Phantom Dependency)

npm v3 이후 node_modules 를 평탄화(hoisting) 하는 전략을 사용한다. 즉, 모든 패키지와 그 하위 의존성을 node_modules 루트로 끌어올린다.

node_modules/
├── react/           ← package.json 에 직접 명시 ✅
├── loose-envify/    ← react의 의존성인데 루트로 호이스팅됨 ⚠️
└── js-tokens/       ← loose-envify의 의존성인데 루트로 호이스팅됨 ⚠️

이렇게 되면 package.json 에 명시하지 않은 loose-envify 를 코드에서 import 해도 동작한다. 이것이 팬텀 의존성 이다.

왜 위험한가:

// 🐣 영철이가 작성한 코드 — 당장은 동작한다
import looseEnvify from 'loose-envify';
 
// 그러나 react 버전이 올라가서 loose-envify를 더 이상 의존하지 않으면?
// → 이 import 는 "패키지 없음" 에러로 빌드 실패
// → 영수 님 호통: "배포 직전에 왜 빌드가 안 되냐고요!"

🏪 content-addressable store — pnpm의 혁신

글로벌 스토어란

pnpm 은 패키지 파일을 하나의 글로벌 스토어(Content-Addressable Store) 에 딱 한 번만 저장한다.

~/.pnpm-store/
└── v3/
    └── files/
        ├── 00/
        │   └── a4f3e2...  ← SHA-512 해시가 파일명 (react의 index.js)
        ├── 01/
        │   └── b7c8d9...  ← react의 package.json
        └── ff/
            └── 1a2b3c...  ← lodash의 fp.js

핵심 원리: 파일의 내용(Content)이 주소(Address)가 된다.

파일 내용의 SHA-512 해시값이 스토어 경로가 된다. 파일 내용이 같으면 해시값이 같으므로, 완전히 동일한 파일은 스토어에 단 하나만 존재 한다.

react@18.2.0 의 index.js 내용 → SHA-512 해시 → 00/a4f3e2...
react@18.2.1 의 index.js 가 달라진 줄이 있으면 → 다른 해시 → 01/x9y8z7...

결론: react@18.2.0 과 18.2.1 이 1개의 파일만 다르다면,
      스토어에는 다른 1개 파일만 추가된다. 나머지는 공유.

스토어 위치 확인

pnpm store path
# /home/user/.pnpm-store/v3

🔗 하드링크 vs 심링크 — 두 개의 무기

pnpm 은 스토어에서 node_modules 로 파일을 복사하지 않는다. 대신 두 종류의 링크를 사용한다.

하드링크 (Hard Link) — 스토어 → .pnpm

글로벌 스토어의 파일
~/.pnpm-store/v3/files/00/a4f3e2...
         ↕ 하드링크 (동일 inode, 동일 파일 데이터)
프로젝트/node_modules/.pnpm/react@18.2.0/node_modules/react/index.js

하드링크의 특성:

• 같은 파일 데이터(inode)를 두 경로가 동시에 가리킨다
• 어느 쪽을 봐도 동일한 내용
• 디스크 공간을 추가로 사용하지 않는다 — 포인터만 추가됨
• 하나를 삭제해도 나머지 경로에서 파일이 유지됨

# 실제로 확인해보면
ls -li node_modules/.pnpm/react@18.2.0/node_modules/react/index.js
# 78453201 ... index.js
 
ls -li ~/.pnpm-store/v3/files/00/a4f3e2...
# 78453201 ... a4f3e2...  ← inode 번호가 동일!

심링크 (Symbolic Link) — .pnpm → 프로젝트 루트

프로젝트/node_modules/react
         ↕ 심링크 (바로가기)
프로젝트/node_modules/.pnpm/react@18.2.0/node_modules/react/

심링크의 특성:

• Windows 바로가기 아이콘과 같은 개념
• 원본 경로를 가리키는 포인터
• node_modules 루트에는 직접 의존성만 심링크로 등장

전체 구조 다이어그램

프로젝트/node_modules/
├── react → .pnpm/react@18.2.0/node_modules/react  (심링크 ✅ 직접 의존성)
├── next  → .pnpm/next@14.2.0/node_modules/next    (심링크 ✅ 직접 의존성)
└── .pnpm/
    ├── react@18.2.0/node_modules/
    │   ├── react/          → 하드링크 → ~/.pnpm-store/...
    │   └── loose-envify/   → 하드링크 → ~/.pnpm-store/...
    └── next@14.2.0/node_modules/
        ├── next/           → 하드링크 → ~/.pnpm-store/...
        └── ...

결론:
- node_modules 루트에는 package.json 에 적은 패키지만 보임
- loose-envify 같은 간접 의존성은 루트에서 보이지 않음 → 팬텀 의존성 원천 차단

🚀 pnpm 설치 3단계 파이프라인

npm 은 "의존성 해결 → 패키지 다운로드 → 설치" 를 순차적으로 처리하지만, pnpm 은 파이프라인 방식 으로 세 단계를 병렬화한다.

npm 방식 (순차):
[Resolve 전체 완료] → [Fetch 전체 완료] → [Write 전체 완료]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
패키지 A: Resolve ──────────────── Fetch ──────── Write
패키지 B:                         Resolve ─────── Fetch ─── Write
패키지 C:                                         Resolve ── Fetch ── Write
...느림

pnpm 방식 (파이프라인):
패키지 A: [Resolve] → [Fetch] → [Link]
패키지 B:   [Resolve] → [Fetch] → [Link]
패키지 C:     [Resolve] → [Fetch] → [Link]
→ 패키지 A 가 resolve 되는 순간 fetch 시작, fetch 되는 순간 link 시작
→ 훨씬 빠름

추가로, 글로벌 스토어에 이미 있는 파일은 다운로드조차 하지 않는다. 하드링크 생성만으로 끝난다.

⚖️ npm vs pnpm 한눈에 비교

⚙️ pnpm 설치 & 프로젝트 첫 세팅

pnpm 설치 (권장: Corepack)

# Node.js 18.19+ / 20.6+ 에 내장된 Corepack 활용
corepack enable
corepack prepare pnpm@latest --activate
 
# 버전 확인
pnpm --version
# 9.x.x

# 또는 npm 으로 전역 설치 (간단한 방법)
npm install -g pnpm

package.json 에 패키지 매니저 고정

// package.json
{
  "name": "youngsu-community",
  // 🦁 [초핵심] 이 레포지토리는 무조건 이 버전의 pnpm만 쓰겠다고 못 박는 설정입니다.
  // 팀원이 실수로 npm install 이나 yarn install 을 치면 "에러! pnpm 쓰세요!" 하고 막아줍니다.
  "packageManager": "pnpm@9.15.0"
}

.npmrc 설정 (pnpm 전용)

# .npmrc (프로젝트 최상단 영역에 생성)
 
# 🦁 엄격 모드 — pnpm은 기본적으로 package.json에 명시되지 않은 패키지(phantom dependency)를 import하면 에러로 차단합니다.
# 하지만 아래 적힌 녀석들은 예외적으로 루트 폴더에 노출시켜서(호이스팅), 기존 도구들이 오류 없이 찾을 수 있게 해줍니다.
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
 
# npm처럼 모든 의존성을 다 루트로 끌어올리는 "창피한(shameful)" 행동은 절대 안 하겠다는 굳은 의지!
shamefully-hoist=false
 
# Node.js 버전을 package.json의 engines 필드에 적힌 버전으로 엄격하게 제한
engine-strict=true

Next.js 프로젝트 생성

# create-next-app 으로 생성하면서 pnpm 사용
pnpm create next-app@latest youngsu-community
 
# 기존 npm 프로젝트를 pnpm 으로 전환
# (07편 마이그레이션 가이드에서 상세 다룸)
pnpm import          # package-lock.json → pnpm-lock.yaml 변환 (가장 먼저!)
rm package-lock.json
pnpm install

기본 명령어 대응표

🏁 총정리

pnpm 핵심 멘탈 모델 3줄 요약
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 글로벌 스토어: 같은 파일은 전 지구에서 딱 한 번만 저장
2. 하드링크:     스토어 → .pnpm (복사 없이 포인터만)
3. 심링크:       .pnpm → node_modules 루트 (직접 의존성만 노출 → 팬텀 의존성 차단)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 한 줄 기억법: npm 은 패키지를 복사 하고, pnpm 은 포인터 를 만든다.

📝 마무리 퀴즈

Q1. pnpm 의 content-addressable store 는 파일을 어떤 기준으로 저장하며, 이것이 디스크 절약에 어떻게 연결되는가?

✅ 정답: 파일 내용의 SHA-512 해시값 을 파일명(주소)으로 사용하여 저장한다. 파일 내용이 동일하면 해시가 같으므로 스토어에 단 하나의 파일 만 존재한다. 100개 프로젝트에서 동일한 react@18.2.0 을 쓴다면 스토어에는 react 파일이 1벌만 있고, 각 프로젝트의 node_modules 는 하드링크로만 연결된다.

💡 상세 해설:

• npm 방식: 프로젝트마다 node_modules/react/ 에 파일을 물리적으로 복사 → 10개 프로젝트 = 10배 용량
• pnpm 방식: ~/.pnpm-store/v3/files/해시/ 에 한 번만 저장 + 하드링크로 연결 → 추가 디스크 사용 없음
• 📌 핵심 기억법: "Content가 Address다" — 내용이 같으면 주소가 같아서 중복이 없다.

Q2. pnpm 이 node_modules 루트에 직접 의존성만 심링크로 노출하는 것이 왜 팬텀 의존성을 차단하는가?

✅ 정답: npm 의 호이스팅 은 간접 의존성도 루트로 끌어올려서 코드에서 직접 import 할 수 있게 만든다. pnpm 은 루트에 package.json 에 명시한 직접 의존성만 심링크로 노출하고, 간접 의존성은 .pnpm/패키지명@버전/node_modules/ 안에만 존재한다. 따라서 명시하지 않은 패키지를 import 하면 Module Not Found 에러 가 즉시 발생한다.

💡 상세 해설:

• 팬텀 의존성의 위험: package.json 에 없는 패키지를 쓰다가, 상위 패키지가 해당 의존성을 제거하면 런타임 에러 발생
• pnpm 의 방어: 루트에 없는 패키지는 Node.js resolve 알고리즘이 찾지 못함 → 개발 단계에서 즉시 에러
• 📌 핵심 기억법: "나한테 소개받지 않은 사람은 파티에 못 들어온다" — package.json 에 없으면 node_modules 루트에 없다.

Q3. 영철이의 테스트 타임: 라이브러리 트레이드오프 (팀 전체 회의)

영수 님이 팀 회의에서 말했다.
"저희 프로젝트 5개 다 npm 쓰는데, 영호 님이 pnpm 으로 바꾸자고 하시는데 어떻게 생각해요? 근데 pnpm 이 심링크 쓰다 보면 일부 도구랑 호환 안 되는 경우도 있다고 들었는데..."

각 캐릭터 관점에서 pnpm 의 장단점은 무엇인가?

✅ 정답: pnpm 의 장점 은 디스크 절약, 설치 속도, 팬텀 의존성 차단이며, 단점 은 일부 도구가 심링크를 따라가지 못하는 호환성 이슈 가 발생할 수 있다는 점이다. 이는 .npmrc 의 shamefully-hoist=true 또는 nodeLinker=hoisted 설정으로 npm 방식으로 폴백할 수 있다.

💡 상세 해설:

• 🦁 영호(원리): "content-addressable store 와 하드링크 덕분에 모노레포 환경에서 특히 효과적이에요. 의존성 격리도 보장되고요."
• 👔 영수(안정성): "일부 Electron 앱, 구형 Jest config, 특정 webpack 플러그인이 심링크를 resolve 못할 수 있어요. 팀에서 먼저 테스트하고 전환해야 해요."
• 🎨 영숙(UX): "설치 속도가 빨라지면 개발 서버 재시작도 빨라지니까 개발 경험(DX)이 좋아지죠."
• 절충안: 호환성 문제가 있는 경우 .npmrc 에 public-hoist-pattern[]=*eslint* 처럼 특정 패키지만 선택적으로 호이스팅 가능
• 📌 핵심 기억법: "pnpm 의 엄격함이 가끔 구형 도구에겐 벽이 된다. 그 벽을 허물려면 shamefully-hoist 라는 이름부터 쑥스럽게 써야 한다."

🐣 영철이의 퇴근 일기

오늘 드디어 pnpm 을 제대로 이해했다. 사실 그동안 "npm 이랑 명령어만 조금 다른 거 아냐?" 라고 생각했는데 완전히 틀린 생각이었다.

하드링크가 포인터라는 개념이 처음엔 좀 헷갈렸는데, 영호 리드 님이 "바탕화면 바로가기 아이콘을 백 개 만들어도 원본 파일이 백 개가 되지는 않잖아요?" 라고 하시니까 딱 이해됐다. 하드링크는 그것보다 더 강한 버전이고.

팬텀 의존성이라는 개념도 오늘 처음 제대로 알았다. package.json 에 없는 패키지를 쓰다가 어느 날 갑자기 빌드 실패하면 진짜 패닉이겠다. pnpm 이 이걸 구조적으로 막아준다는 게 꽤 인상적이었다.

💡 오늘의 교훈: "npm 은 패키지를 '복사' 하고, pnpm 은 '포인터' 를 만든다. 같은 결과물이지만 디스크 비용이 전혀 다르다."

집 가는 길에 SSD 용량 확인해봤더니 아직도 node_modules 가 18GB 를 먹고 있다. 내일 출근하면 바로 pnpm 설치하고 프로젝트들 전환해봐야지. 오늘 배운 걸 써먹어보자!

🔗 더 알아보기

• pnpm 공식 문서 - Motivation
• pnpm 공식 문서 - Symlinked node_modules structure
• Flat node_modules is not the only way (pnpm 블로그)
• pnpm vs npm 공식 비교