ENES

ADR 001: Module Federation v2 for Micro Frontend Composition

Status: Accepted Date: 2025-03-15 Last Updated: 2026-02-26

Context

We need a runtime composition strategy for 5-10 micro frontends that allows independent deployment, shared dependency management, and dynamic loading.

Decision

Use Module Federation 2.0.1 stable (@module-federation/enhanced ^2.0.1) with Rsbuild/Rspack. The @module-federation/rsbuild-plugin (^2.0.1) is used for Rsbuild integration. Note: the npm package version now aligns with the architectural "v2" naming -- the 2.0.x releases represent the stable release of what was previously tracked under 0.x pre-release versions.

Key Dependencies

  • @module-federation/enhanced: ^2.0.1
  • @module-federation/rsbuild-plugin: ^2.0.1
  • react: ^19.2.4 (shared singleton)
Module Federation v2 Decision Card Module Federation v2 Positive Runtime composition Shared dep negotiation Dynamic remote loading TypeScript type gen Negative Steeper learning curve Complex debugging HMR limitations

Consequences

Positive

  • Runtime composition: no build-time coordination between MFEs
  • Shared dependency negotiation (React ^19.2.4 singleton)
  • Dynamic remote loading via runtime API
  • TypeScript type generation across repo boundaries
  • mf-manifest.json protocol for version negotiation
  • Chrome DevTools plugin for debugging
  • Active development and growing ecosystem

Negative

  • Steeper learning curve than simpler approaches (import maps)
  • Debugging shared dependency issues can be complex
  • HMR limitations across remote boundaries
  • pnpm compatibility requires careful configuration (.npmrc hoisting)
  • Version postfix bugs in shared dependency resolution

Alternatives Considered

  • single-spa: Framework-agnostic but more complex setup, less mature sharing of dependencies, requires a custom import map service. MF 2.0.1 handles dependency sharing natively.
  • qiankun (based on single-spa): Good for legacy integration but overkill for React-only platform. Less ecosystem support outside Chinese market.
  • Native import maps: Simple but no shared dependency management, no type safety, no manifest protocol. Would require building all these features from scratch.
  • Webpack Module Federation v1: Lacks runtime API, no dynamic remote registration, no manifest protocol, no type generation.
NextADR 002: Cloudflare Workers as Edge Platform