Catalog My learning Blog
Micro-Frontends Course: React, Import Maps and Teams · Phase 4 · Lesson 15 · 5 min read

Micro-Frontend Governance and Migration

On this page
  1. Standardize the seams, not the insides
  2. Who owns what
  3. Migrating from a monolith
  4. When to merge back
  5. Capstone: the composed shop
  6. Check yourself

Standardize the seams, not the insides

Teams need freedom inside their area, or there's no point to micro-frontends. But some things must be the same everywhere, or the product falls apart. A useful rule: standardize what crosses a boundary; leave alone what doesn't.

Standardize (the seams)Leave to each team (the insides)
The mount contract and its propsState management inside the micro-frontend
Event names and payloadsComponent structure and folder layout
Design tokens and the design systemTesting tools, as long as contract tests run
The shared React versionData fetching library
Auth through the BFF, the bff() helperInternal routing library
Error reporting, budgets, the deploy pipelineRelease frequency

Write the left column down as a short platform guide, and keep it short. A guide nobody can read in ten minutes won't be followed.

Who owns what

  • Each product team owns one to three micro-frontends end to end: code, tests, deploys, errors and budgets.
  • The platform team owns the shell, the import map service, the deploy pipeline, the contract package and shared tooling. Its customers are the product teams.
  • The design system team owns tokens and components, released as a versioned package.

Make decisions about the seams through short written proposals, often called architecture decision records, that every team can comment on. A change to the contract or an event is a cross-team API change, and it deserves that much ceremony.

Migrating from a monolith

Few teams start with micro-frontends. Most migrate an existing single-page app. Do it gradually, using the strangler fig pattern: new parts grow around the old app until it can be removed.

  1. Turn the existing app into the first micro-frontend. Wrap it in a mount function and put a thin shell in front of it. Nothing visible changes, but the plumbing (import map, deploy pipeline, error attribution) is now in place.
  2. Move one area with a clear owner, ideally one that changes often, like the account section. Route /account to the new micro-frontend and everything else still to the old app.
  3. Repeat, one area at a time, each move releasable on its own. The old app shrinks.
  4. Retire the old app when nothing routes to it.

During the migration, the old app and new micro-frontends share the page, often with different React versions. Day 9's scopes and the mount contract make that safe. If the old app is too tangled to mount, an iframe is an acceptable temporary boundary (Day 7).

When to merge back

Micro-frontends aren't forever. Consider merging two of them back into one when:

  • the same team ends up owning both,
  • most features need changes in both,
  • the boundary between them causes more events and contract changes than real independence.

Merging is a sign of a healthy architecture that follows the organization, not a failure.

Capstone: the composed shop

Bring the course together by building the shop from this course end to end. Check each item:

  1. Boundaries. Catalog, cart, account and header, split by business area, each with a named owning team (Days 1 and 2).
  2. Contract. A @shop/contract package with Mount, MountProps, ShopEvents, the emit and on helpers and the bff() fetch helper (Days 4, 8 and 11).
  3. Composition. Each micro-frontend built separately with React external, one shared React through the import map, and hashed files with immutable caching (Day 5).
  4. Shell. Prefix routing with a navigation token, popstate support, deep links, Promise.allSettled at boot and a fallback per area (Day 6).
  5. Isolation. At least one web component with shadow DOM, styles scoped with @scope or naming, all CSS in layers (Days 7 and 10).
  6. Communication. Typed events for "item added" and "cart changed", with confirmation in the UI, and the URL for shareable state (Day 8).
  7. Auth. One BFF session cookie, a user prop from the shell, one session-expired flow and full-navigation sign-out (Day 11).
  8. Tests. Unit tests per team, the contract harness with an explicit listener allowlist, shared event examples, two end-to-end journeys and one resilience test (Day 12).
  9. Deploys. An import map service where each pipeline updates only its own entry, one-click rollback, a canary bucket, and old files kept for weeks (Day 13).
  10. Production. Error boundaries, error attribution by file, per-team budgets in CI and reserved space for each mount area (Day 14).

If every item works, you have a micro-frontend platform that delivers on the one promise that justifies it: teams that ship on their own schedule without breaking each other. The combined course later in this series connects this shop to a BFF and typed tRPC APIs end to end.

TipRun a "chaos day" on staging before launch. Break one micro-frontend's file, slow another's data, throw in a third's render, and expire the session. Walk through the shop and confirm every failure stays inside its own area.

Check yourself

No. State management stays inside a micro-frontend, so it's each team's choice. Standardize only what crosses boundaries, like the contract, events and design tokens.

Wrap the existing app as the first micro-frontend behind a thin shell, so the shell, import map and pipeline exist before any code moves.

Merging them. Once one team owns both and most features touch both, the boundary no longer buys any independence; it only adds events, contract changes and two pipelines to keep in step. Merging is a healthy sign that the architecture is following the organization.

Run it in an iframe for the routes it still owns. The iframe gives it a separate document, so its global CSS and JavaScript can't break the new micro-frontends. It's heavy and awkward for focus and deep links, so plan to retire it as areas move out.

Every team that emits or listens to that event, typically through a short written proposal and required reviews on the contract package. Events are a public API between teams, so a change deserves the same care as an API change.