pnpm 모노레포 React 19 마이그레이션: 숨겨진 호이스팅 레이어로 인한 타입 충돌 해결

pnpm workspace 기반 모노레포 환경에서 React 19로의 단계적 마이그레이션을 위해 pnpm catalogs 기능을 도입했다. 이를 통해 기존 React 18 앱과 신규 React 19 앱의 의존성을 독립적으로 격리하여 버전 파편화를 방지하고자 했다.

하지만 마이그레이션 과정에서 기존 React 18 앱들이 React 19의 타입을 참조하게 되는 타입 오염(Type Pollution) 현상이 발생했다. 이로 인해 children이나 ReactNode 타입 추론이 어긋나며 다수의 TypeScript 에러가 쏟아졌다.

문제의 원인은 pnpm의 독특한 node_modules 구조에 있었다. pnpm은 Global Store와 Hard Link를 활용해 효율성을 높이고, Symbolic Link를 통해 유령 의존성을 차단하는 3계층 구조를 가진다.

• Layer 1 (Strict Interface Layer): 각 앱의 node_modules로, package.json에 명시된 패키지만 심볼릭 링크로 연결되어 독립성을 보장한다.
• Layer 2 (.pnpm Virtual Store): 의존성 그래프의 실제 구현체이자 심볼릭 링크가 가리키는 목적지다.