Architecture · Micro-frontends

Where micro-frontend boundaries should actually go

Module federation, web components and iframes are implementation details. The hard question is who owns which slice of the product, and what the pieces are allowed to assume about each other. Get that wrong and no amount of tooling saves you.

I have worked on micro-frontend programmes that made delivery faster and on ones that quietly became a distributed monolith with more pipelines. The difference was rarely the bundler. It was whether the boundaries matched the organisation, and whether the contracts between the pieces were small enough to keep.

1. A micro-frontend is an ownership boundary, not a folder

Start with the team map, not the component tree. A useful boundary has three properties:

  • It has a clear owner. One team can decide what changes, release it, and be accountable for its quality.
  • It delivers a complete user outcome. A vertical slice such as “checkout” or “fleet diagnostics” is a better boundary than “all forms” or “the shared header”.
  • It can change without coordinated releases. If every change needs three teams in a room, you have a module, not a micro-frontend.

If the organisation has one frontend team, the honest answer is usually a modular monolith with strong internal boundaries. Micro-frontends add network, versioning and observability costs that only pay off when independent ownership is real.

2. Define the shell contract first

The shell — the application that composes the page — is the most important piece to design early, because every other decision depends on it. It should own as little product logic as possible and provide exactly these things:

  • Layout and composition: where a remote mounts, and what space it gets.
  • Routing: the top-level URL structure, plus a documented way for a remote to own its sub-routes.
  • Identity and session: authentication state, current user, permissions and tenant. Remotes consume it; they do not each implement their own auth flow.
  • Cross-cutting services: notifications, telemetry, feature flags, error reporting, localization and the design system.
  • Lifecycle: mount, unmount, error and retry. A remote that fails must not take the page down with it.

Write the contract as types and documentation, not as a wiki page that drifts. If a remote needs something new from the shell, that is a versioned change with a migration path — not a Slack message.

3. Split vertically, not by layer

The most common mistake is splitting by technical layer: one remote for the header, one for forms, one for charts, one for the footer. That creates a dependency graph where every product change touches several repositories and every release is a coordination exercise.

Split by business capability instead. A team that owns “billing” should own its routes, state, API calls, components and tests. The shell should not know how billing calculates a total; it should only know where billing renders and what user context it needs.

Good boundary Painful boundary
Checkout, owned end to end by one team All buttons, owned by a “UI platform” team
Device fleet diagnostics All charts in the product
Account administration and permissions All forms across every domain

4. Share less than you think

Every shared dependency is a runtime and release coupling. A small, deliberate shared layer is healthy; a large one recreates the monolith without the tooling.

Share through the shell Keep inside the remote
Design-system components and tokens Feature-specific state and API clients
Authentication and user context Business rules for that domain
Logging, metrics and error reporting Local caches and optimistic updates
Routing primitives and navigation events Internal component structure and styling

Be especially careful with shared state. A global store that every remote writes to is a distributed database with no schema, no transactions and no owner. Prefer explicit events or a narrow, read-mostly context object. If two remotes genuinely need to collaborate, treat that as a product boundary problem and reconsider the split.

5. Make the contract explicit and versioned

The shell and each remote should agree on a small interface: the inputs it receives, the events it emits and the browser APIs it may use. Anything else is private.

export interface RemoteContext {
  readonly locale: string;
  readonly user: { id: string; roles: string[]; tenantId: string };
  readonly navigate: (path: string) => void;
  readonly notify: (message: string, level: 'info' | 'error') => void;
}

export interface RemoteHandle {
  mount(target: HTMLElement, context: RemoteContext): Promise<void>;
  unmount(): Promise<void>;
}

Version the contract and support at least one previous version during a migration. Log which remote version is running in production; when something breaks, you need to know what changed without guessing. Avoid exposing the shell’s internal framework objects as part of the contract — that turns an implementation detail into a public API.

6. The independent-deploy test

This is the test I use to decide whether a split is real. Can one team, on a normal Tuesday, change their remote, run their own pipeline, and have it live for a subset of users without any other team deploying, approving or even being awake?

If the answer is no because of a shared lockfile, a shared release train, a shared bundle or a shared database migration, then the boundary is organisational theatre. Either fix the coupling or merge the slices back together.

7. Design for failure and observability

Distributed frontends fail in more ways than a single application: a remote chunk can 404, an API contract can drift, a slow remote can block a route. The shell needs:

  • A timeout and an error boundary per remote, with a useful fallback rather than a blank page.
  • Retry with a version pin, so a bad deploy can be rolled back independently.
  • Per-remote performance and error telemetry, tagged with the version.
  • Load-order rules that keep the critical path small: render the primary task first, load secondary panels after.

8. Know when not to do this

Micro-frontends are a solution to an organisational scaling problem. They are a poor answer to a purely technical one. If the product is small, the team is one team, or the main problem is an inconsistent UI, a design system and a modular monolith will deliver more value with far less operational cost.

9. The short checklist

  • One team, one vertical slice, one deployable unit.
  • Shell owns composition, auth, routing, telemetry and design tokens; nothing else.
  • Shared state is narrow, explicit and read-mostly.
  • Contracts are typed, versioned and documented.
  • Independent deploy is proven, not assumed.
  • Every remote has an error boundary, a timeout and versioned telemetry.
  • The decision is revisited when the team topology changes.

Boundaries are a design decision about people first and code second. When they match how the organisation actually works, micro-frontends disappear into the background and delivery gets faster. When they do not, the architecture becomes a second job.

Related reading: how to keep the shared layer consistent in design systems that survive, and the release-safety checks in the Angular performance checklist.

Back to top