Module Federation: singleton이면 당연히 하나겠죠?
Summary
'singleton: true'만 켜면 끝난 줄 알았던 모듈 페더레이션의 반전과 잔혹사
채널톡 코어웹팀이 여러 개의 React 인스턴스와 깨진 Context 문제를 추적하며 세운 기술 트러블슈팅 가이드
마이크로 프론트엔드 환경에서 Module Federation의 singleton 옵션을 적용하더라도 런타임 분리, 서브패스 매칭 미흡, 패키지 매니저의 peerDependency 해석 차이로 인해 인스턴스가 파편화될 수 있습니다. 본 아티클은 실제 프로덕션 환경에서 발생한 싱글톤 인스턴스 중복 문제를 근본적으로 분석하고 해결 기준을 정립한 여정을 담고 있습니다.
- 01호스트의 다중 진입점으로 인한 모듈 캐시 중복을 optimization.runtimeChunk: 'single' 설정으로 해결
- 02React Query 등 개별 상태 관리가 필요한 라이브러리를 무조건 싱글톤화할 때 생기는 부작용 검증 및 우회 패턴 적용
- 03패키지의 서브패스(예: /beta) 사용 시 Webpack shared 키 매칭 원리로 인해 별도 인스턴스가 생기는 현상 규명
- 04pnpm 패키지 매니저의 peerDependency 해석 특성으로 인한 중복 설치 문제를 pnpm catalog로 제어
RECOMMENDATION
Module Federation 기반 마이크로 프론트엔드를 구축 중이거나, 원인 모를 React Hook/Context 에러로 고통받는 프론트엔드 아키텍트와 대규모 모노레포 관리자에게 강력 추천합니다.
The Problem
마이크로 프론트엔드 전환 중 Module Federation(MF)을 도입하면서 React 훅 에러 및 컨텍스트(Context) 값이 초기화되는 문제가 발생했습니다. 이는 호스트와 리모트 번들, 또는 호스트 내부의 다중 진입점(entry)으로 인해 동일한 라이브러리 인스턴스가 런타임 모듈 캐시상에서 여러 벌 생성되었기 때문입니다.
The Solution
Webpack의 shared singleton 옵션을 설정하고, runtimeChunk: 'single'을 적용해 호스트의 런타임을 하나로 합쳤습니다. 또한 서브패스(subpath)를 shared 키에 명시적으로 추가하고, pnpm 카탈로그를 활용해 peerDependency 버전 불일치로 인한 인스턴스 중복 생성을 방지했습니다.
The Result
단일 인스턴스 참조가 보장되어 훅 에러와 컨텍스트 유실 문제를 해결했으며, 리모트가 호스트 인스턴스를 직접 참조해야 하는 경우에만 싱글톤으로 등록하는 명확한 기술 판단 기준을 세웠습니다.
Trade-off
eager: true 및 싱글톤 처리된 패키지는 트리쉐이킹(tree-shaking)이 적용되지 않아 초기 번들 용량이 증가할 수 있으므로, React Query처럼 감싼 훅으로 우회 가능한 라이브러리는 무조건 공유 대상에 포함하지 않는 타협이 필요합니다.
