Micro-Frontend Governance and Migration
On this page
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 props | State management inside the micro-frontend |
| Event names and payloads | Component structure and folder layout |
| Design tokens and the design system | Testing tools, as long as contract tests run |
| The shared React version | Data fetching library |
Auth through the BFF, the bff() helper | Internal routing library |
| Error reporting, budgets, the deploy pipeline | Release 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.
- Turn the existing app into the first micro-frontend. Wrap it in a
mountfunction 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. - Move one area with a clear owner, ideally one that changes often, like the account section. Route
/accountto the new micro-frontend and everything else still to the old app. - Repeat, one area at a time, each move releasable on its own. The old app shrinks.
- 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:
- Boundaries. Catalog, cart, account and header, split by business area, each with a named owning team (Days 1 and 2).
- Contract. A
@shop/contractpackage withMount,MountProps,ShopEvents, theemitandonhelpers and thebff()fetch helper (Days 4, 8 and 11). - Composition. Each micro-frontend built separately with React external, one shared React through the import map, and hashed files with immutable caching (Day 5).
- Shell. Prefix routing with a navigation token,
popstatesupport, deep links,Promise.allSettledat boot and a fallback per area (Day 6). - Isolation. At least one web component with shadow DOM, styles scoped with
@scopeor naming, all CSS in layers (Days 7 and 10). - Communication. Typed events for "item added" and "cart changed", with confirmation in the UI, and the URL for shareable state (Day 8).
- Auth. One BFF session cookie, a
userprop from the shell, onesession-expiredflow and full-navigation sign-out (Day 11). - 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).
- 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).
- 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.
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.