02. node_modules 구조 해부

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🔬 .pnpm 폴더 해부
• 🔀 피어 의존성과 심링크의 관계
• 📌 호이스팅 제어
• 🎛️ nodeLinker 설정
• 🛠️ 실전 트러블슈팅

8. 총정리
9. 마무리 퀴즈
10. 영철이의 퇴근 일기
11. 더 알아보기

📌 이 문서를 읽기 전에

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

🗺️ 이 문서의 흐름

[.pnpm 폴더 구조] → [피어 의존성 처리] → [호이스팅 제어] → [nodeLinker 옵션] → [에러 해결]

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

• .pnpm 폴더 내부 구조를 직접 탐색하고 해석할 수 있다
• 피어 의존성 버전이 다를 때 pnpm 이 어떻게 처리하는지 설명할 수 있다
• public-hoist-pattern 으로 특정 패키지를 선택적으로 호이스팅할 수 있다
• nodeLinker 옵션의 차이를 알고 상황에 맞게 선택할 수 있다

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

• 🐣 영철 ( 신입 ): "영호 님, pnpm 으로 바꿨는데 ESLint가 갑자기 안 되요. Cannot find module 'eslint' 라고 나오는데 분명히 devDependencies 에 있거든요. 그리고 node_modules 폴더 들어가봤는데 eslint 폴더가 없고 .pnpm 이라는 숨김 폴더만 있어서 뭔가 설치가 잘못된 것 같아요. pnpm install 다시 해봤는데도 똑같고..."
• 🦁 영호 ( 리드 ): "영철 님, .pnpm 폴더 안을 열어봤어요? eslint 가 거기 있을 거예요. pnpm 은 루트 node_modules 에는 package.json 에 직접 적힌 패키지만 심링크로 노출하거든요. ESLint 가 없다는 에러는 십중팔구 ESLint 플러그인이 루트 node_modules 에서 eslint 를 찾으려고 하는데 못 찾는 케이스예요. .npmrc 에 public-hoist-pattern[]=*eslint* 한 줄 추가하면 해결돼요."

🤔 왜 알아야 하는가

pnpm 을 처음 도입하는 팀의 90% 가 비슷한 경험을 한다.

"잘 되던 eslint, jest, tailwind 설정이 pnpm 으로 바꾸고 나서 갑자기 안 된다."

이것은 pnpm 의 버그가 아니다. pnpm 의 철학이 npm 과 근본적으로 다르기 때문 에 발생하는 자연스러운 마찰이다. .pnpm 폴더의 구조를 이해하면 이런 에러가 왜 발생하는지, 어떻게 해결해야 하는지를 명확하게 알 수 있다.

🔬 .pnpm 폴더 해부

실제 구조 탐색

영수네 커뮤니티 프로젝트에서 ls node_modules/.pnpm 을 실행하면:

node_modules/
├── .modules.yaml           ← pnpm 메타데이터 (버전, 설정 등)
├── next → .pnpm/next@14.2.0/node_modules/next          (심링크)
├── react → .pnpm/react@18.2.0/node_modules/react       (심링크)
├── typescript → .pnpm/typescript@5.3.3/node_modules/typescript (심링크)
└── .pnpm/
    ├── next@14.2.0/
    │   └── node_modules/
    │       ├── next/           ← 하드링크 → 글로벌 스토어
    │       ├── react/          ← 심링크 → .pnpm/react@18.2.0/...  (next의 피어)
    │       └── postcss/        ← 하드링크 → 글로벌 스토어 (next의 deps)
    ├── react@18.2.0/
    │   └── node_modules/
    │       ├── react/          ← 하드링크 → 글로벌 스토어
    │       └── loose-envify/   ← 하드링크 → 글로벌 스토어 (react의 deps)
    └── typescript@5.3.3/
        └── node_modules/
            └── typescript/     ← 하드링크 → 글로벌 스토어

네이밍 규칙: 패키지명@버전

.pnpm 내부의 폴더명은 패키지명@버전 형식이다. 피어 의존성의 버전이 달라지면 폴더명도 달라진다(아래에서 자세히 다룸).

.modules.yaml — pnpm 의 메타 정보

# node_modules/.modules.yaml
# 💡 pnpm이 node_modules 폴더 전체를 관리할 때 참고하는 "내부 장부" 같은 파일입니다.
hoistedDependencies:
  /eslint@8.57.0:
    eslint: public # 루트 폴더로 끌어올려진(hoisting) 패키지 목록을 보여줍니다.
layoutVersion: 5
packageManager: pnpm@9.15.0
pendingBuilds: []
publicHoistPattern:
  # .npmrc에서 설정한 호이스팅 규칙이 이 장부에 그대로 반영되어 동작합니다.
  - '*types*'
  - '*eslint*'
prunedAt: 2026-03-05 # 마지막으로 불필요한 패키지(쓰레기)를 청소한 날짜
registries:
  default: https://registry.npmjs.org/
storeDir: /home/user/.pnpm-store/v3 # 내 컴퓨터 안의 진짜 원본 파일들이 숨어있는 글로벌 저장소 위치
virtualStoreDir: .pnpm # 심링크와 하드링크의 마법이 일어나는 가상 저장소 이름

🔀 피어 의존성과 심링크의 관계

피어 의존성이 다른 버전으로 설치될 때

피어 의존성(peerDependencies)은 패키지가 "호스트 프로젝트에서 제공해야 한다"고 선언하는 의존성이다. 예를 들어 react-query 는 react@>=18 을 피어로 요구한다.

만약 모노레포에서 패키지 A 는 react@17, 패키지 B 는 react@18 을 피어로 사용하는 플러그인이 있다면, pnpm 은 어떻게 처리할까?

node_modules/.pnpm/
├── some-plugin@1.0.0_react@17.0.2/   ← react@17 과 함께 해결된 버전
│   └── node_modules/
│       ├── some-plugin/
│       └── react/  → .pnpm/react@17.0.2/...
└── some-plugin@1.0.0_react@18.2.0/   ← react@18 과 함께 해결된 버전
    └── node_modules/
        ├── some-plugin/
        └── react/  → .pnpm/react@18.2.0/...

폴더명이 패키지명@버전_피어패키지@피어버전 형식으로 분기된다. 피어가 다르면 사실상 다른 설치 컨텍스트이므로, pnpm 이 이를 별도 폴더로 격리한다.

npm 은 이 문제를 "그냥 둘 다 호이스팅" 하거나 하나를 택해서 처리하는데, pnpm 은 명확하게 분리 한다.

autoInstallPeers 설정

# .npmrc 또는 pnpm-workspace.yaml
# 피어 의존성을 자동으로 설치할지 여부 (pnpm 기본값: true)
auto-install-peers=true

📌 호이스팅 제어 — public-hoist-pattern

왜 호이스팅이 필요한 경우가 있는가

pnpm 의 엄격한 격리는 대부분의 경우 좋지만, 일부 도구는 루트 node_modules 에서 특정 패키지를 찾기 때문에 심링크 구조에서 에러가 난다.

대표적인 예:

❌ 에러 케이스들:
- ESLint 플러그인이 루트 node_modules 에서 eslint 바이너리를 찾을 때
- TypeScript 가 @types/* 를 루트에서 찾을 때
- Prettier 플러그인이 루트 prettier 를 찾을 때
- 일부 Jest 설정이 루트 jest-* 를 찾을 때

public-hoist-pattern 설정

.npmrc 에서 패턴 매칭으로 특정 패키지만 선택적으로 루트에 호이스팅 할 수 있다.

# .npmrc (영수네 커뮤니티 권장 설정 / 프로젝트 루트)
 
# 🦁 pnpm의 기본 원칙은 "package.json에 없는 애들은 숨긴다" 지만, 예외를 허용해 줍니다.
# TypeScript가 코드를 작성할 때 자동완성(intellisense)을 해주려면 타입 정의 파일들이 필요한데, 얘네는 예외로 루트에 둡니다.
public-hoist-pattern[]=*types*
 
# ESLint 역시 플러그인들이 루트 폴더에서 본체를 찾으려는 버릇이 있어서 예외로 둡니다.
public-hoist-pattern[]=*eslint*
 
# 코드 포매터인 prettier 계열도 예외.
public-hoist-pattern[]=prettier
 
# 만약 이름에 공통점이 없다면? 정확하게 콕 집어서 지정할 수도 있습니다.
public-hoist-pattern[]=next

# 극단적인 경우: npm 처럼 모든 패키지를 호이스팅 (비추천)
# 팬텀 의존성 차단 효과가 사라짐
shamefully-hoist=true

🦁 영호 리드의 조언:

shamefully-hoist=true 는 이름부터 "창피한 호이스팅" 이에요.
pnpm 을 쓰면서 npm 처럼 동작하게 만드는 옵션이라 이름을 이렇게 지은 거예요.
호이스팅이 필요하다면 shamefully-hoist 대신
public-hoist-pattern 으로 필요한 것만 정확하게 지정하세요.

Next.js 프로젝트 권장 .npmrc

# .npmrc (Next.js를 쓸 때 이 정도는 넣어줘야 속이 편합니다)
 
# 💡 TypeScript types 호이스팅 (VSCode 등 에디터에서 빨간줄 안 뜨게 하려면 필수!)
public-hoist-pattern[]=*types*
 
# 💡 ESLint 계열 호이스팅 (Next.js의 기본 eslint-config-next가 루트의 eslint를 찾기 때문)
public-hoist-pattern[]=*eslint*
 
# 💡 Tailwind CSS와 관련된 친구들을 호이스팅 (Tailwind가 플러그인들을 못 찾는 에러 방지)
public-hoist-pattern[]=tailwindcss
public-hoist-pattern[]=postcss
public-hoist-pattern[]=autoprefixer
 
# 💡 [중요] 버전이 다르면 에러! (팀원 간, 혹은 서버 간 환경 일치 목적)
engine-strict=true

🎛️ nodeLinker 설정 — 엄격함의 스펙트럼

pnpm 은 nodeLinker 설정으로 node_modules 생성 방식을 선택할 수 있다.

# pnpm-workspace.yaml 또는 .npmrc
# nodeLinker=isolated   (기본값 — 심링크 격리 구조)
# nodeLinker=hoisted    (npm 방식과 유사한 평탄화)
# nodeLinker=pnp        (Yarn PnP 방식)

nodeLinker=isolated (기본값)

node_modules/
├── react → .pnpm/react@18.2.0/...    (심링크, 직접 의존성만)
└── .pnpm/
    └── react@18.2.0/node_modules/react/  (하드링크 → 스토어)

장점: 팬텀 의존성 차단, 디스크 절약
단점: 심링크를 못 따라가는 구형 도구와 호환 이슈

nodeLinker=hoisted

node_modules/
├── react/        (하드링크 → 스토어, npm 처럼 루트에 배치)
├── loose-envify/ (react 의 deps 도 루트로 호이스팅)
└── .pnpm-store → 글로벌 스토어 (하드링크는 유지)

장점: npm/Yarn Classic 과 동일한 구조라 호환성 최고
단점: 팬텀 의존성 발생 가능

nodeLinker=pnp (Plug'n'Play)

.pnp.cjs  ← 의존성 맵을 파일 하나에 담음
.pnp.loader.mjs
(node_modules 폴더 없음)

장점: node_modules 자체가 없어 가장 빠름 (Zero-Install 가능)
단점: 도구 호환성 가장 낮음, 설정 복잡

언제 어떤 걸 쓰는가

🛠️ 실전 트러블슈팅 — 심링크로 인한 에러 해결

케이스 1: Cannot find module 'eslint'

# 에러
Error: Cannot find module 'eslint'
Require stack:
- /home/user/projects/youngsu-community/node_modules/.pnpm/eslint-config-next@14.2.0/node_modules/eslint-config-next/index.js

원인: eslint-config-next 가 루트 node_modules 에서 eslint 를 찾으려 함
해결:

# .npmrc 에 추가
public-hoist-pattern[]=*eslint*

pnpm install  # 재설치하면 eslint 가 루트로 호이스팅됨

케이스 2: PostCSS / Tailwind 설정 에러

# 에러
Error: Cannot find module 'tailwindcss/resolveConfig'

해결:

# .npmrc 에 추가
public-hoist-pattern[]=tailwindcss
public-hoist-pattern[]=postcss

케이스 3: Prisma 생성 파일 인식 못함

# 에러
Cannot find module '@prisma/client'

원인: Prisma 는 postinstall 시 node_modules/.prisma/client 에 파일을 생성하는데, pnpm 의 격리 구조에서 경로가 다름
해결:

// package.json scripts 에 추가
{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

케이스 4: 심링크를 따라가지 못하는 구형 도구

# 최후의 수단 — .npmrc
shamefully-hoist=true
# 또는
node-linker=hoisted

🏁 총정리

pnpm node_modules 구조 핵심 정리
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
루트 node_modules: package.json 직접 의존성만 심링크로 노출
.pnpm/:           모든 패키지 + 간접 의존성이 하드링크로 저장
피어 의존성:       버전이 다르면 .pnpm/패키지@버전_피어@버전 으로 분리
호이스팅 제어:     public-hoist-pattern 으로 선택적 루트 노출
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 마무리 퀴즈

Q1. .pnpm 폴더 내의 서브 폴더명이 some-plugin@1.0.0_react@17.0.2 처럼 피어 버전까지 포함되는 이유는 무엇인가?

✅ 정답: 동일한 패키지라도 피어 의존성 버전이 다르면 서로 다른 실행 컨텍스트 이기 때문이다. some-plugin 이 react@17 과 react@18 환경에서 각각 다른 동작을 할 수 있으므로, pnpm 은 이를 별도 폴더로 격리 하여 두 버전이 공존할 수 있도록 한다.

💡 상세 해설:

• npm 은 피어 의존성 충돌을 "그냥 설치하거나 경고만 출력" 하는데, 이는 런타임 에러로 이어질 수 있다
• pnpm 은 피어 버전까지 폴더명에 포함시켜 완전히 격리 → 같은 패키지의 두 컨텍스트가 안전하게 공존
• 📌 핵심 기억법: "피어가 다르면 사실 다른 패키지다 — pnpm 이 이 사실을 폴더명으로 표현한다."

Q2. public-hoist-pattern 과 shamefully-hoist 의 차이는 무엇이며, 어떤 상황에서 각각을 사용하는가?

✅ 정답: public-hoist-pattern 은 패턴에 일치하는 패키지만 선택적으로 루트 node_modules 에 호이스팅한다. shamefully-hoist=true 는 모든 패키지를 npm 방식처럼 루트로 호이스팅하여 팬텀 의존성을 허용한다. 전자는 pnpm 의 격리 철학을 유지하면서 특정 도구 호환성 문제를 해결할 때, 후자는 빠른 마이그레이션이나 구형 도구 때문에 어쩔 수 없을 때만 쓴다.

💡 상세 해설:

• public-hoist-pattern[]=*eslint* → eslint 관련 패키지만 루트 노출, 나머지 격리 유지
• shamefully-hoist=true → pnpm 을 npm 처럼 만들어버림 (이름부터 "창피한" 이유)
• 📌 핵심 기억법: "외과 수술(public-hoist-pattern) vs 전신마취(shamefully-hoist) — 가능하면 외과 수술을 택하라."

Q3. 영철이의 테스트 타임: 긴급 디버깅 (영수의 호통)

영수 님이 Slack 으로 메시지를 보냈다.
"영철 님, QA 서버에서 빌드 실패했어요. Cannot find module 'typescript' 에러인데 로컬에서는 잘 되거든요? 오늘 pnpm 으로 바꾼 거랑 관련 있나요?"

영철이가 확인해보니 로컬 .npmrc 에는 public-hoist-pattern[]=*types* 가 있는데 QA 서버의 .npmrc 에는 없었다. 이 상황의 근본 원인과 해결책은?

✅ 정답: .npmrc 파일이 환경마다 달라서 발생한 문제다. .npmrc 는 프로젝트 루트에 커밋 되어야 모든 환경에서 동일한 hoisting 설정이 적용된다. 해결책은 프로젝트 루트의 .npmrc 에 필요한 public-hoist-pattern 설정을 추가하고 git 에 커밋하는 것이다.

💡 상세 해설:

• .npmrc 는 여러 위치에서 로드됨: 프로젝트 루트 → 홈 디렉토리(~/.npmrc) → 전역
• 로컬 개발자의 ~/.npmrc 에만 있던 설정이 CI/QA 서버에는 없는 경우가 흔한 함정
• 올바른 관리: 프로젝트별 pnpm 설정은 .npmrc(프로젝트 루트) 에 두고 git 에 커밋
• 주의: 토큰(_authToken) 같은 민감한 정보는 절대 git 에 커밋하지 말 것 (환경변수 사용)
• 📌 핵심 기억법: "설정은 코드다 — .npmrc 도 git 으로 관리하라."

🐣 영철이의 퇴근 일기

오늘 오전에 pnpm 으로 바꿨다가 ESLint 가 안 돼서 한 시간 날렸다. .pnpm 폴더 안에 eslint 가 잘 있는데 왜 못 찾냐고 답답해서 스택 오버플로우를 헤맸다.

결국 영호 리드 님한테 물어봤는데 .npmrc 한 줄이 답이었다. public-hoist-pattern[]=*eslint*. 뭔가 되게 간단한 해결이었는데 원리를 모르니까 한 시간이나 허비한 거였다.

그나저나 .pnpm 폴더 구조가 진짜 신기하다. some-package@1.0.0_react@18.2.0 이런 이름으로 피어 의존성 버전까지 폴더명에 박아버리는 방식이 처음엔 이상해보였는데, 알고 보니까 엄청 영리한 설계였다. 피어가 다르면 다른 컨텍스트라는 걸 폴더 구조로 표현하는 거잖아.

💡 오늘의 교훈: "pnpm 에서 '모듈 못 찾겠다'는 에러는 십중팔구 .npmrc 에 public-hoist-pattern 을 추가하면 해결된다. 구조를 알면 당황하지 않는다."

내일은 pnpm CLI 명령어랑 pnpm-lock.yaml 구조 공부해야지. 오늘은 치킨 먹고 일찍 자야겠다. 머리가 무거워.

🔗 더 알아보기

• pnpm - Symlinked node_modules structure
• pnpm - How peers are resolved
• pnpm - .npmrc settings
• pnpm - nodeLinker settings