07. npm → pnpm 마이그레이션

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• ✅ 마이그레이션 전 체크리스트
• 🪜 단계별 마이그레이션 루틴
• 🚧 흔한 함정과 해결책
• 👥 팀 온보딩 & CI/CD 전환
• 📦 모노레포 마이그레이션

8. pnpm 의 알려진 제한사항
9. 총정리
10. 마무리 퀴즈
11. 영철이의 퇴근 일기
12. 더 알아보기

📌 이 문서를 읽기 전에

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

🗺️ 이 문서의 흐름

[전환 전 체크리스트] → [단계별 마이그레이션] → [함정 해결] → [팀 온보딩] → [제한사항 인식]

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

• npm/Yarn 프로젝트를 pnpm 으로 안전하게 전환하는 7단계 루틴을 실행할 수 있다
• 마이그레이션 후 발생하는 흔한 에러를 스스로 진단하고 해결할 수 있다
• CI/CD, GitHub Actions, Docker 를 pnpm 기준으로 업데이트할 수 있다
• pnpm 의 알려진 제한사항을 팀에게 사전에 안내할 수 있다

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

• 🐣 영철 ( 신입 ): "영호 님, 드디어 영수 님이 pnpm 전환 승인해주셨어요! 근데 막상 시작하려니 어디서부터 해야 할지 모르겠어요. 그냥 npm install 대신 pnpm install 하면 되는 건가요? 기존 package-lock.json 은 어떻게 하고, .github/workflows 도 바꿔야 하나요? CI 에서 배포 파이프라인 도중에 실패하면 되돌릴 수 있나요?"
• 🦁 영호 ( 리드 ): "급하게 하면 꼭 뭔가 빠져요. 순서가 중요해요. pnpm import 로 기존 lock 파일을 변환하고, .npmrc 에서 hoisting 설정을 점검하고, 로컬에서 dev/build/test 다 통과한 뒤에 CI 수정해야 해요. 특히 GitHub Actions 워크플로우 파일은 브랜치를 따로 만들어서 PR 로 검증하고 머지하는 게 안전해요. 서두르지 말고 체크리스트 하나씩 밟아가세요."

🤔 왜 알아야 하는가

pnpm 은 npm 과 개념적으로 다르기 때문에 단순히 명령어만 바꾸면 된다는 생각은 함정이다.

실제로 마이그레이션 도중 자주 겪는 상황:

✅ 로컬에서는 잘 되는데 CI 에서 실패
✅ 빌드는 되는데 ESLint 가 안 됨
✅ 개발 서버는 뜨는데 특정 라이브러리 import 에러
✅ 팀원 A 는 되는데 팀원 B 는 안 됨
✅ Docker 빌드가 갑자기 훨씬 느려짐

이 모든 상황은 체계적인 순서 로 진행하면 대부분 예방할 수 있다.

✅ 마이그레이션 전 체크리스트

마이그레이션 시작 전, 현재 프로젝트 상태를 점검하라.

# 1. 현재 패키지 매니저 확인
cat package.json | grep packageManager
ls -la | grep -E "package-lock|yarn.lock|pnpm-lock"
 
# 2. 사용 중인 npm scripts 확인 (postinstall 이 있는지)
cat package.json | grep -A 20 '"scripts"'
 
# 3. .npmrc 가 있으면 내용 확인
cat .npmrc 2>/dev/null
 
# 4. CI/CD 파일 목록 확인
ls .github/workflows/

체크리스트:

🪜 단계별 마이그레이션 루틴

Step 1: pnpm 설치

# Corepack 으로 설치 (권장)
corepack enable
corepack prepare pnpm@latest --activate
 
# 또는 npm 으로
npm install -g pnpm
 
# 버전 확인
pnpm --version

Step 2: lock 파일 변환

# npm → pnpm: package-lock.json 을 pnpm-lock.yaml 로 변환
pnpm import
 
# yarn.lock → pnpm-lock.yaml
pnpm import
 
# 변환 후 확인
ls pnpm-lock.yaml  # 생성됨

주의: pnpm import 는 기존 lock 파일을 참고해서 pnpm-lock.yaml 을 생성하지만, 100% 동일한 버전이 보장되지 않을 수 있다. 특히 간접 의존성 버전이 달라질 수 있으므로, Step 4 에서 반드시 테스트로 검증한다.

Step 3: 기존 lock 파일 및 node_modules 정리

# 기존 파일 제거
rm -rf node_modules
rm package-lock.json  # npm 이었다면
# rm yarn.lock         # yarn 이었다면
 
# 🦁 .gitignore 에 pnpm-lock.yaml 이 없는지 확인 (있으면 제거)
grep "pnpm-lock" .gitignore

Step 4: .npmrc 설정

# .npmrc (신규로 생성하거나, 기존 파일 맨 위에 이 내용을 추가합니다)
 
# 🦁 [초핵심] Next.js 프로젝트 필수 설정 (호이스팅 허용)
# 원래 pnpm은 숨겨진 의존성을 절대 허용하지 않지만, 아래 적힌 녀석들은 예외로 쳐줍니다.
# 이걸 안 적어주면 ESLint나 Tailwind가 "모듈을 찾을 수 없다"고 파업을 선언합니다.
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=prettier
public-hoist-pattern[]=tailwindcss
public-hoist-pattern[]=postcss
public-hoist-pattern[]=autoprefixer
 
# 🦁 [안전 장치] package.json에 적힌 Node/pnpm 버전이 아니면 설치 자체를 튕겨냅니다.
engine-strict=true

Step 5: pnpm install & 검증

# 새로 설치
pnpm install
 
# 로컬 검증 (이 세 가지 모두 통과해야 다음 단계로)
pnpm dev           # 개발 서버 정상 동작 확인
pnpm build         # 프로덕션 빌드 성공 확인
pnpm test          # 테스트 통과 확인
pnpm lint          # lint 에러 없음 확인
pnpm typecheck     # TypeScript 에러 없음 확인

Step 6: package.json 업데이트

// package.json
{
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=20.0.0",
    "pnpm": ">=9.0.0"
  },
  "scripts": {
    // npm ci → pnpm install --frozen-lockfile
    // npx → pnpm dlx
    "postinstall": "prisma generate"  // 그대로 유지 (pnpm 도 실행함)
  }
}

Step 7: git 커밋

git add pnpm-lock.yaml .npmrc package.json
git rm package-lock.json  # 또는 yarn.lock
git commit -m "chore: npm → pnpm 마이그레이션
 
- package-lock.json → pnpm-lock.yaml 변환 (pnpm import)
- .npmrc 추가 (public-hoist-pattern 설정)
- package.json 에 packageManager 필드 추가
- engines 필드 업데이트 (node>=20, pnpm>=9)"

🚧 흔한 함정과 해결책

함정 1: ESLint / TypeScript 관련 에러

Error: Cannot find module 'eslint'
Error: Cannot find module '@types/react'

해결:

# .npmrc 에 호이스팅 패턴 추가
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*

pnpm install  # 재설치하면 적용됨

함정 2: Prisma generate 실패

Error: @prisma/client did not initialize yet.
Please run "prisma generate"

해결:

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

함정 3: Husky hooks 가 동작하지 않음

.husky/pre-commit not found

해결:

# husky 재초기화
pnpm dlx husky install
 
# 또는 package.json 의 prepare 스크립트
{
  "scripts": {
    "prepare": "husky"
  }
}

함정 4: 팬텀 의존성으로 인한 빌드 에러

Error: Cannot find module 'some-package'
# package.json 에 없는 패키지를 직접 import 하고 있었음

해결:

# 어떤 패키지인지 확인
pnpm why some-package
 
# package.json 에 명시적으로 추가
pnpm add some-package

이 에러는 npm 에선 팬텀 의존성으로 동작하다가 pnpm 에서 정상적으로 차단된 케이스다. 수정이 필요한 코드 품질 문제 이므로 반드시 package.json 에 추가해야 한다.

함정 5: 특정 라이브러리가 심링크를 따라가지 못함

Error: ENOENT: no such file or directory, scandir '.../node_modules/...'

해결 (단계적 접근):

# 1단계: 해당 패키지만 선택적으로 호이스팅
public-hoist-pattern[]=문제가되는패키지명
 
# 2단계: 그래도 안 되면 nodeLinker 를 hoisted 로 변경
# pnpm-workspace.yaml 또는 .npmrc
node-linker=hoisted

함정 6: Docker 빌드 시 corepack 미설치

# ❌ 문제 있는 Dockerfile
FROM node:20-slim
RUN npm install -g pnpm  # 이렇게 하면 버전 불일치 가능
 
# ✅ 올바른 방법
FROM node:20-slim
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
# package.json 의 packageManager 버전으로 자동 활성화됨

함정 7: pnpm-lock.yaml 이 .gitignore 에 포함된 경우

# .gitignore 확인
grep "pnpm-lock" .gitignore
 
# 있다면 제거
# pnpm-lock.yaml 은 반드시 git 에 커밋해야 함
# (npm 의 package-lock.json 과 동일한 역할)

👥 팀 온보딩 & CI/CD 전환

팀원 온보딩 안내문 템플릿

## pnpm 으로 전환되었습니다 🎉
 
### 설치
\`\`\`bash
corepack enable
pnpm --version  # 9.x.x 가 표시되면 완료
\`\`\`
 
### 기존 명령어 → 새 명령어
| 기존 | 변경 |
|------|------|
| npm install | pnpm install |
| npm install 패키지 | pnpm add 패키지 |
| npm install -D 패키지 | pnpm add -D 패키지 |
| npm uninstall 패키지 | pnpm remove 패키지 |
| npm run dev | pnpm dev |
| npx create-next-app | pnpm dlx create-next-app |
| npm ci | pnpm install --frozen-lockfile |
 
### 주의사항
- \`package-lock.json\` 은 더 이상 사용하지 않아요
- \`pnpm-lock.yaml\` 이 새로운 lock 파일이에요 (커밋 필수)
- \`node_modules\` 구조가 달라 보여도 정상이에요

GitHub Actions 전환

# 💡 CI 파이프라인 (GitHub Actions) 전환 전후 비교
 
# ❌ 변경 전 (npm 시절) ❌
- name: Install
  run: npm ci # 패키지 설치에만 2~3분이 걸리던 시절
 
# --------------------------------------------------
 
# ✅ 변경 후 (pnpm 도입) ✅
# 1️⃣ 컴퓨터에 pnpm을 깔아주는 마법의 Action
- name: Setup pnpm
  uses: pnpm/action-setup@v4
  # (여기에 version: 9 라고 쓰지 않아도 package.json의 packageManager를 알아서 읽습니다!)
 
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: 20
    # 2️⃣ [핵심] 이거 한 줄만 쓰면 끝! pnpm 글로벌 저장소가 통째로 캐싱됩니다.
    cache: 'pnpm'               
 
- name: Install
  # 3️⃣ 배포 시점에는 무조건 lock 파일을 신뢰해야 하므로 --frozen-lockfile을 씁니다. (npm ci 와 똑같은 역할)
  # 위에서 캐시가 성공적으로 적용되었다면 설치가 15초 컷으로 끝납니다!
  run: pnpm install --frozen-lockfile

Dependabot 설정 (변경 없음)

# .github/dependabot.yml
# npm ecosystem 이 pnpm-lock.yaml 도 지원함 — 변경 불필요
version: 2
updates:
  - package-ecosystem: "npm"   # npm 그대로 사용
    directory: "/"
    schedule:
      interval: "weekly"

📦 모노레포 마이그레이션

기존 Lerna, Yarn Workspaces 에서 pnpm workspace 로 전환할 때.

Yarn Workspaces → pnpm workspace

# 변경 전: package.json workspaces 필드
# {
#   "workspaces": ["apps/*", "packages/*"]
# }
 
# 변경 후: pnpm-workspace.yaml 신규 생성
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

# package.json 에서 workspaces 필드 제거
# yarn.lock 제거
rm yarn.lock
rm -rf node_modules apps/*/node_modules packages/*/node_modules
 
# pnpm 으로 재설치
pnpm install

workspace: 프로토콜 변환

// 변경 전 (Yarn)
{ "@youngsu/ui": "*" }
 
// 변경 후 (pnpm)
{ "@youngsu/ui": "workspace:*" }

⚠️ pnpm 의 알려진 제한사항

마이그레이션 전에 팀에게 공유해야 할 제한사항들.

1. 하드링크가 지원되지 않는 환경

Docker 빌드 시 컨테이너-호스트 간 하드링크 생성 불가
→ Docker 내부에서 pnpm 을 사용할 때는 하드링크 대신 복사(copy)
→ 성능 저하는 없으나 BuildKit 캐시로 보완

해결: --mount=type=cache 사용 (06편 참고)

2. 심링크를 따라가지 못하는 구형 도구

일부 Electron 앱, 구형 webpack config, 특정 Jest transform 이
심링크를 따라가지 못하는 경우 발생

해결 방법 (선호도 순):
1. public-hoist-pattern 으로 해당 패키지 호이스팅
2. nodeLinker=hoisted (npm 방식으로 폴백)
3. shamefully-hoist=true (최후의 수단)

3. 일부 패키지의 postinstall 스크립트 실행 차이

npm 은 기본적으로 모든 postinstall 을 실행하지만
pnpm 은 보안상 일부 패키지의 빌드 스크립트를 기본적으로 승인 필요

해결:
pnpm approve-builds     # 한 번 실행하면 ~/.pnpm-state 에 승인 목록 저장
또는
# pnpm-workspace.yaml
onlyBuiltDependencies:
  - esbuild
  - sharp

4. Zero-Install 미지원

Yarn PnP 의 Zero-Install (node_modules 없이 .yarn/cache 를 git 에 커밋)
은 pnpm 에서 지원하지 않음

pnpm 의 대안: pnpm install --offline 으로 스토어 기반 오프라인 설치

🏁 총정리

마이그레이션 7단계 체크리스트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: pnpm 설치 (corepack enable)
Step 2: pnpm import (lock 파일 변환)
Step 3: 기존 node_modules / package-lock.json 삭제
Step 4: .npmrc 설정 (public-hoist-pattern)
Step 5: pnpm install + dev/build/test 검증
Step 6: package.json 에 packageManager / engines 추가
Step 7: git commit (pnpm-lock.yaml 포함)
+추가: CI/CD, Docker 업데이트 (별도 PR 권장)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 마무리 퀴즈

Q1. pnpm import 로 변환한 pnpm-lock.yaml 이 완전히 동일한 버전을 보장하지 않는 이유와, 이를 검증하는 방법은?

✅ 정답: pnpm import 는 기존 lock 파일의 정보를 참고하지만, pnpm 의 의존성 해결 알고리즘 이 npm/Yarn 과 다르기 때문에 일부 간접 의존성의 버전이 달라질 수 있다. 검증 방법은 변환 후 반드시 pnpm dev, pnpm build, pnpm test 를 모두 실행해서 동작을 확인하고, 특히 pnpm list --depth=3 으로 핵심 패키지의 버전을 확인하는 것이다.

💡 상세 해설:

• 직접 의존성 버전은 대부분 유지되지만, 간접 의존성(transitive)은 다를 수 있음
• 특히 피어 의존성 해석 방식이 달라 일부 패키지가 다른 버전으로 설치될 수 있음
• 가장 안전한 방법: package.json 의 직접 의존성은 버전을 명확하게 고정하고 (e.g., "react": "18.2.0" exact) 변환 후 검증
• 📌 핵심 기억법: "import 는 번역이지 복사가 아니다 — 반드시 검증 테스트를 돌려라."

Q2. 마이그레이션 후 팬텀 의존성 에러 (Cannot find module 'X') 가 발생했을 때, 이를 수정하는 두 가지 올바른 접근법은?

✅ 정답: 올바른 방법 은 두 가지다. 첫째, 해당 패키지를 package.json 에 명시적으로 추가 (pnpm add X) 하는 것이다 — 팬텀 의존성을 실제 의존성으로 격상시킨다. 둘째, pnpm why X 로 출처를 확인해서 실제로 필요 없다면 해당 import 문을 제거 하는 것이다. shamefully-hoist=true 로 에러를 숨기는 것은 문제를 감추는 것이지 해결이 아니다.

💡 상세 해설:

• 팬텀 의존성은 "npm 에선 운 좋게 됐던 코드 품질 문제" — pnpm 이 올바르게 차단한 것
• pnpm add X 로 추가 → 이후 X 가 직접 의존성이 돼서 안전
• shamefully-hoist 는 임시방편이지 코드 품질 해결이 아님
• 📌 핵심 기억법: "팬텀 에러 = pnpm 이 잡아준 코드 빚 — 도망치지 말고 pnpm add 로 갚아라."

Q3. 영철이의 테스트 타임: 실무 딜레마 (영철의 선택)

영철이가 마이그레이션 후 CI 에서만 에러가 발생한다.

Error: Cannot find module 'eslint'

로컬에서는 잘 되는데 GitHub Actions 에서만 안 된다.
가능한 원인을 2가지 이상 제시하고, 각각의 확인 방법과 해결책을 설명하라.

✅ 정답: 원인 1: 로컬 ~/.npmrc 에 public-hoist-pattern[]=*eslint* 가 있지만 프로젝트 .npmrc 에는 없는 경우. 원인 2: CI workflow 에서 pnpm/action-setup 이 없거나 cache: 'pnpm' 이 누락되어 캐시 없이 새로 설치하면서 동작이 달라지는 경우. 원인 3: workflow 에 여전히 npm ci 가 남아있는 경우.

💡 상세 해설:

• 원인 1 확인: cat .npmrc vs cat ~/.npmrc 비교 / 해결: 프로젝트 .npmrc 에 패턴 추가 후 커밋
• 원인 2 확인: workflow 에 pnpm/action-setup@v4 스텝이 있는지 확인 / 해결: setup 스텝 추가
• 원인 3 확인: workflow 에 npm ci 가 있는지 grep / 해결: pnpm install --frozen-lockfile 으로 교체
• 핵심 원칙: "로컬 OK, CI 실패 = 환경 설정이 다른 것이다 — 프로젝트 루트 파일로 통일하라."
• 📌 핵심 기억법: "설정은 홈 디렉토리가 아닌 프로젝트 루트 .npmrc 에 — 그래야 CI 도 같다."

🐣 영철이의 퇴근 일기

드디어 pnpm 가이드 7편 마지막이다.

솔직히 마이그레이션 챕터가 처음엔 별거 없을 것 같았는데, 막상 정리하다 보니 함정이 생각보다 많았다. 팬텀 의존성 에러, 로컬-CI 환경 차이, Husky hooks 재설정, Prisma postinstall... 하나하나는 별게 아니지만 동시에 여러 개가 터지면 정말 패닉이 올 수 있겠다 싶었다.

영호 리드 님이 "급하게 하면 꼭 뭔가 빠진다"고 하신 말씀이 이제서야 진짜로 이해됐다. 체크리스트 하나씩 밟아가는 게 결국 가장 빠른 길이다. 급하게 달리다가 빠진 거 찾으러 되돌아가는 것보다.

pnpm 가이드 7편을 처음부터 끝까지 다 썼다. 멘탈 모델, node_modules 구조, CLI, workspace, Catalogs, CI/Docker, 그리고 마이그레이션까지. 처음 pnpm 을 알았을 때 "그냥 npm 이랑 비슷한 거 아냐?" 라고 생각했는데, 이제 pnpm 이 얼마나 다르고 얼마나 잘 설계된 도구인지 제대로 알게 됐다.

💡 오늘의 교훈: "마이그레이션은 결승선이 아니라 출발선이다. 순서를 지키고, 검증하고, 팀에게 공유하면 — 그때부터 pnpm 의 진짜 이점을 누릴 수 있다."

내일부터는 실제 프로젝트에 pnpm 을 적용해볼 차례다. 이론은 충분히 쌓았다. 이제 실전이다. 영호 리드 님이 잘 했다고 스티커 하나 주셨다. 오늘은 기분 좋게 집 가서 맛있는 거 먹어야지.

🔗 더 알아보기

• pnpm import 공식 문서
• pnpm 제한사항 공식 문서
• pnpm FAQ
• pnpm 마이그레이션 가이드 (공식)
• only-allow — 패키지 매니저 강제