pnpm Workspaces의 Strict Isolation으로 인한 CI 빌드 실패 및 모듈 해석 오류 해결

pnpm workspaces en monorepo con Next.js 16: lo que el benchmark no midió y casi me rompe el CI

Juan Torchia2026년 5월 11일13분intermediate

AI 요약

Context

Next.js 16 App Router와 pnpm Workspaces를 결합한 Monorepo 구조에서 CI 환경의 비결정적 모듈 해석 문제 발생. 단순 Install Time 벤치마크로는 확인 불가한 Dependency Hoisting 및 Cache Invalidation 이슈가 빌드 파이프라인의 병목과 런타임 에러를 유발한 상황.

Technical Solution

pnpm의 Strict Isolation 모델로 인한 Node_modules 계층 구조와 Turbopack의 모듈 해석 알고리즘 간의 불일치 해결
서로 다른 Patch 버전의 Peer Dependency가 Store 내에 중복 생성되어 발생하는 모듈 충돌 방지
.npmrc 설정을 통한 public-hoist-pattern 적용으로 React 등 핵심 라이브러리의 Hoisting 제어
shamefully-hoist=true 옵션을 통한 npm/yarn 방식의 공격적 Hoisting으로 의존성 해석 일관성 확보
pnpm.overrides 설정을 통해 Monorepo 전체의 의존성 버전을 강제로 동기화하여 중복 인스턴스 제거
Lockfile 기반의 정밀한 Cache Key 설정을 통해 CI 환경의 비결정적 빌드 동작 제거

실천 포인트

- pnpm Workspaces 도입 시 `pnpm why <package> --recursive` 명령어로 중복 의존성 인스턴스 존재 여부 확인 - Next.js Turbopack 사용 시 `.npmrc` 내 Hoisting 패턴 설정을 통해 모듈 해석 경로 최적화 - Monorepo 내 공유 패키지와 앱 간의 Peer Dependency 버전 일치 여부 검증 - CI 환경에서 `Cannot find module` 에러 발생 시 단순 경로 문제가 아닌 Hoisting 및 Cache 상태 점검

태그

#Dependency Hoisting #Turbopack #pnpm Workspaces #Monorepo #Next.js 16

원문 읽기