Micro-frontends skill for Claude Code

Micro-frontends solve an organizational problem (teams blocking each other’s releases), not a technical one. Done well means: the split passed the team-topology test in writing, there is one composition approach with a stated reason, users see one product (one design system, one copy of the framework, no extra navigation latency inside a team’s area), and every app ships to production without coordinating a release with another team.

Ground rules

• Default to a modular monolith frontend. Split only when the topology test below passes.
• Split vertically (by route or business area, owned end to end by one team) before horizontally (several teams’ fragments on one page). Horizontal splits cost the most.
• One framework major version across apps that share a page. “Each team picks its own framework” is a migration state, not a target architecture.
• Shared code is a versioned package with an owner, never a copied folder.
• Nothing crosses an app boundary except URLs, typed events, and published packages. No shared mutable global store.
• Every remote can fail. The host must render a fallback, never a blank page.

Workflow

- [ ] 1. Run the team-topology test; write down the result
- [ ] 2. If it fails: modular monolith frontend (stop here, see "When not to split")
- [ ] 3. Draw the split: which team owns which routes and which page fragments
- [ ] 4. Pick the composition approach (default: route-level apps behind a proxy)
- [ ] 5. Define the shared-dependency contract and the design-system package
- [ ] 6. Define routing ownership and the cross-app event contract
- [ ] 7. Set per-app performance budgets and wire them into CI
- [ ] 8. Set up independent deploys: immutable versioned assets, manifest pointer, rollback
- [ ] 9. Verify: fallback on remote failure, single framework copy, budgets, deep links

1. Team-topology test

Answer each question with evidence (team charts, release history, CI times), not opinion:

Question	Points toward splitting when
How many teams ship to this frontend?	Several stream-aligned teams, each owning a distinct business area
Do releases block each other?	Teams wait on a shared release train, freeze, or another team’s failing tests
Can areas map to routes?	Most features live under a team-owned URL prefix (/billing/*, /catalog/*)
Different lifecycles?	A legacy app must be replaced incrementally (strangler migration)
Is there platform capacity?	Someone will own the shell, shared packages, CI templates, and budgets

Split only when the first three point toward splitting and someone owns the platform work. One team, or several teams that already release independently from a monorepo, gains nothing but overhead. A strangler migration is the one case where a single team can justify a temporary split: retire the old app, then fold back.

When not to split: modular monolith frontend

If the test fails, deliver the same isolation inside one deployable:

• One app, feature folders per business area, each with a public index.ts.
• Enforce boundaries in CI (ESLint import rules, Nx module-boundary tags, or dependency-cruiser) so areas cannot import each other’s internals.
• Route-level code splitting gives each area its own chunks; CODEOWNERS gives each team review ownership of its folder.
• Fix the actual pain first: slow CI (affected-only builds, caching), merge conflicts (smaller modules), release trains (trunk-based development with feature flags).

3–4. Composition approaches

Approach	How	Use when	Cost
Route-level apps behind a proxy or edge (default)	Each team deploys a full app for its URL prefixes; a reverse proxy, CDN, or edge rewrite routes paths	Vertical split; navigation between areas is infrequent	Hard navigation (full page load) when crossing apps
Build-time packages	Teams publish npm packages; the shell bundles them	Shared widgets, not independent deploys	Every change needs a shell rebuild and release — this is not independent deployment
Runtime JS: Module Federation 2.0	Host loads remotes’ exposed modules at runtime, sharing singletons	Several teams must render on the same page or keep SPA navigation across areas	Version skew, runtime failure modes, harder debugging
Runtime JS: single-spa + import maps	Root config mounts framework apps per route	Mixed frameworks during a migration	Lifecycle glue per app; extra runtime
Server or edge HTML composition	Server-side includes, ESI, or an edge worker stitches HTML fragments	Content-heavy pages, SEO-critical, little client state	Fragment caching and hydration coordination
Iframes	Each fragment is a separate document	Untrusted or third-party content, hard isolation, legacy embedding	Routing, focus, resizing, accessibility and performance all get harder

Rules of thumb:

• Start with the default. Escalate to Module Federation only for a concrete same-page requirement, and record it in the decision.
• Next.js: use Multi-Zones (separate apps per path set, assetPrefix per zone, rewrites in the main app). Link across zones with a plain <a>, not <Link>, because <Link> prefetches and soft-navigates. The @module-federation/nextjs-mf plugin supports only the Pages Router and has been announced end-of-life; do not start new work on it.
• Vite: @module-federation/vite. Webpack and Rspack: @module-federation/enhanced (/webpack, /rspack entry points) or the Rsbuild plugin.

For Module Federation host and remote configuration, the runtime API, manifests, and failure handling, read references/module-federation.md when the chosen approach is runtime composition.

5. Shared dependencies and the design system

Classify every dependency:

Class	Examples	Rule
Must be a single instance	react, react-dom, router, design-system context providers, i18n runtime	Shared as singleton with a requiredVersion range; one version policy across apps
Should share when compatible	Date libraries, data-fetching clients	Shared without singleton; duplicates allowed on major mismatch
App-private	Feature libraries	Bundled per app; never shared

• Version policy: a central file (or Renovate group) pins the allowed major for each singleton. Upgrading a singleton major is a coordinated, scheduled change — the one place where independence ends. Plan for it.
• Design system: a versioned package (tokens as CSS custom properties plus components). Remotes must not ship global resets or element selectors (body, h1, *).
• CSS isolation: CSS Modules or a per-app class prefix by default; wrap app styles in a cascade layer (@layer app-billing) so ordering is predictable. Shadow DOM isolates fully but blocks shared tokens unless they are custom properties, and complicates portals, focus, and third-party widgets.

6. Routing ownership and communication

Routing:

• The shell (or proxy config) owns the top-level route table: prefix to app. Each app owns everything under its prefix, including its own 404 inside the prefix.
• The route table is a contract: keep it in one file, review changes, and test that each prefix resolves to the right app.
• Deep links and refresh must work on every route. Test them, not just in-app navigation.
• With a runtime host, the host owns the history instance; remotes receive a base path and navigate through a function the host passes in, never by writing to window.history directly.

Communication, in order of preference:

1. URL and query string (shareable, survives reload).
2. Props or a small API the host passes when mounting a remote.
3. Typed custom DOM events for fire-and-forget notifications.
4. Backend as the source of truth (both apps read the same API).

// packages/contracts/src/events.ts — published, versioned, owned by the platform team
export type CartItemAdded = { v: 1; sku: string; quantity: number };

export const CART_ITEM_ADDED = "shop:cart:item-added" as const;

export function emitCartItemAdded(detail: CartItemAdded) {
  window.dispatchEvent(new CustomEvent<CartItemAdded>(CART_ITEM_ADDED, { detail }));
}

• Namespace event names by domain; include a version field in the payload; add fields, never repurpose them.
• Auth: one session cookie on the shared domain, read by each app’s backend. Never pass tokens through events or localStorage shared between apps.

7. Performance budget

Composition must not cost the user. Budget per app and for the composed page:

• JS shipped per route (compressed) and the count of framework copies — exactly one.
• No request waterfall: host, then remote entry, then the remote’s chunks. Preload remote entries for the current route and use the manifest so assets are known up front.
• Core Web Vitals at p75 for each app’s routes, tracked separately per app so a regression has an owner.
• Check for duplicate packages in each build (bundle analyzer, npm ls <pkg>); a second React or design-system copy is a release blocker.
• Enforce in CI with a size checker on each app’s build output; fail the build on breach.

8. Independent deploys and versioning

• Publish every remote build to an immutable, versioned path (/billing/2026-10-14-ab12cd/), long-cache those assets, and point to the live version through a small, short-cache manifest (or the MF mf-manifest.json URL).
• Rollback is repointing the manifest, not a rebuild. Confirm with the user before repointing production.
• Contracts (exposed module props, events, routes) change backward-compatibly: add, then migrate consumers, then remove in a later release.
• Expect skew: an open tab can run an old host with a new remote. Exposed modules must tolerate missing optional props; a failed chunk load should trigger a reload prompt.
• Contract-test exposed modules (render with the props the host passes) in the remote’s own CI, and run a smoke test of the composed app against production remotes after each deploy.

Gotchas

• Two copies of React load when a remote is built without the shared singleton or the version ranges do not overlap. Symptoms: “Invalid hook call”, context not found.
• eager: true on shared modules puts them in the entry chunk and inflates every app; use an async boundary (import("./bootstrap")) instead.
• A remote’s global CSS reset silently restyles the host. Lint remotes for element selectors.
• Cross-app navigation through <Link> or a router that does not know the other app produces 404s or blank screens. Plain links across app boundaries.
• Analytics and error tracking need the app name and version on every event, or regressions cannot be attributed to a team.
• Local development drifts from production when each team runs only its app. Provide a shell that can point at production remotes plus one local remote.

Verification

1. Block one remote’s entry in DevTools (Network request blocking): the page shows the fallback and the rest of the app keeps working.
2. In the Network or Sources panel, confirm exactly one copy of the framework and the design system loads on a composed page.
3. Deep-link and hard-refresh one route per app; each resolves without a client-side 404.
4. Deploy one remote alone and confirm the host picks it up without a host release; repoint the manifest to the previous version and confirm rollback.
5. Run the per-app size and Web Vitals budgets in CI; a deliberately oversized build must fail.

If a check fails, fix the contract (shared config, route table, fallback) before adding more apps.

Output contract

Deliver the decision as a short record:

## Frontend split decision — <product>, <date>
**Topology test:** <teams, release blocking evidence, route mapping, platform owner>
**Decision:** Modular monolith | Route-level apps | Module Federation | <other>
**Reason:** <one paragraph; name the concrete requirement that forced runtime composition, if any>
**Ownership map:** /billing/* → Payments team (app: billing) ...
**Shared singletons and version policy:** react ^19, router, design-system ^4 ...
**Contracts:** route table file, events package, exposed modules
**Budgets:** <JS per route, Web Vitals targets per app>
**Deploy and rollback:** <asset paths, manifest location, rollback step>
**Revisit when:** <trigger, e.g. teams merge, migration finishes>