Micro-frontends

01The idea: split by team and business domain

Imagine an e-commerce site built by six teams: search, product pages, checkout, account, content and marketing. In a single frontend codebase, every change goes through one build and one deploy, and a bug in checkout can block a search release. With micro-frontends, each team owns a vertical slice: its own repository or package, its own pipeline, and its own deploy. A shell (also called host or container app) provides the page frame, routing and shared services, and loads the right micro-frontend for each area. Think of a shopping mall: one building, shared corridors and security, but each shop is run independently. The key principle is to split by business capability, not by technical layer such as 'header team' and 'button team'.

• Shell / host: composes the page and owns routing and global concerns.
• Remote / micro-frontend: an independently deployed part of the UI.
• Contract: the agreed interface between shell and remote (props, events, routes).

02Ways to compose micro-frontends

Composition can happen at different times and places. Build-time integration publishes each part as an npm package that the shell imports; simple and fast, but you lose independent deployment because the shell must rebuild. Server-side composition stitches HTML fragments on the server or edge (Edge Side Includes, a composition service, or framework features such as Next.js Multi-Zones, where different apps own different URL paths behind one domain). Run-time integration loads JavaScript from each team in the browser: Module Federation, import maps with native ES modules, or Web Components. Iframes give the strongest isolation but poor integration for layout, routing and accessibility. The simplest effective approach is often route-level splitting: each team owns whole pages, and only the shell's navigation is shared.

03Module Federation explained

Module Federation, introduced in webpack 5 and now available as a standalone runtime (Module Federation 2.0) with plugins for webpack, Rspack, Rsbuild and Vite, lets one build load modules from another build at run time. A remote exposes modules (for example ./ProductPage) through a small entry file, often called remoteEntry.js or described by an mf-manifest.json. A host declares remotes and imports their modules as if they were local; the code is fetched only when needed. Shared dependencies such as React are declared as singletons so the page loads one copy, with version ranges negotiated at run time. Version 2.0 adds a manifest protocol, type hints for remotes, a runtime plugin system and devtools.

1// rsbuild.config.ts (remote: product team)
2import { defineConfig } from "@rsbuild/core";
3import { pluginReact } from "@rsbuild/plugin-react";
4import { pluginModuleFederation } from "@module-federation/rsbuild-plugin";
5 
6export default defineConfig({
7  plugins: [
8    pluginReact(),
9    pluginModuleFederation({
10      name: "product",
11      exposes: { "./ProductPage": "./src/ProductPage.tsx" },
12      shared: {
13        react: { singleton: true, requiredVersion: "^19.0.0" },
14        "react-dom": { singleton: true, requiredVersion: "^19.0.0" },
15      },
16    }),
17  ],
18  server: { port: 3001 },
19});

04Consuming a remote in the shell

The host declares where each remote lives and lazy-loads its modules. Wrap every remote in an error boundary and a loading fallback: a remote is a network dependency that can fail or be slow, and one broken team must not break the whole page. In production, remote URLs should come from configuration or a manifest service rather than being hard-coded, so teams can deploy and roll back without rebuilding the shell.

1// host: rsbuild.config.ts (excerpt)
2pluginModuleFederation({
3  name: "shell",
4  remotes: { product: "product@https://cdn.example.com/product/mf-manifest.json" },
5  shared: { react: { singleton: true }, "react-dom": { singleton: true } },
6});
7 
8// host: src/routes/ProductRoute.tsx
9import { lazy, Suspense } from "react";
10import { ErrorBoundary } from "react-error-boundary";
11 
12const ProductPage = lazy(() => import("product/ProductPage"));
13 
14export function ProductRoute() {
15  return (
16    <ErrorBoundary fallback={<p>Product details are unavailable right now.</p>}>
17      <Suspense fallback={<p>Loading…</p>}>
18        <ProductPage />
19      </Suspense>
20    </ErrorBoundary>
21  );
22}

05Communication and shared state

Micro-frontends should be loosely coupled, so they communicate through small, explicit contracts rather than a shared global store. Common options: URL and routing as the primary state (the product ID lives in the URL), props passed by the shell when it mounts a remote, browser custom events for notifications like 'cart updated', and backend APIs as the source of truth that each part reads independently. Avoid one global Redux store shared by all teams; it recreates the coupling you split to avoid. Authentication is usually owned by the shell, which provides a token getter or user context through a tiny shared interface.

1// Contract: a typed custom event
2type CartUpdated = { count: number };
3 
4// Checkout micro-frontend
5window.dispatchEvent(new CustomEvent<CartUpdated>("cart:updated", { detail: { count: 3 } }));
6 
7// Shell header
8window.addEventListener("cart:updated", (e) => {
9  const { count } = (e as CustomEvent<CartUpdated>).detail;
10  renderBadge(count);
11});

06Design systems and consistency

The biggest user-visible risk is an inconsistent product: different buttons, spacing and behaviours from each team. A shared design system solves this: design tokens (colours, spacing, typography as CSS variables), a component library published as a versioned package, and documentation in Storybook. Teams consume it like any dependency. Style isolation matters too: use CSS Modules, a prefix per micro-frontend, or Shadow DOM for Web Components, so one team's global CSS does not break another's page. Keep the design system's breaking changes rare and announced, because every team must upgrade; tokens as CSS variables let you change themes at run time without redeploying every remote.

07Monorepo or polyrepo, and the decision itself

Micro-frontends are about independent deployment, not necessarily separate repositories. Many teams use a monorepo (Nx, Turborepo, pnpm workspaces) with one folder per micro-frontend, separate build and deploy pipelines triggered by affected changes, and shared tooling. This keeps refactors and dependency upgrades easy while preserving team ownership. Polyrepos maximise autonomy but make shared upgrades and consistency harder. Before choosing either, ask whether you need micro-frontends at all: with fewer than about three or four frontend teams, a well-structured modular monolith with clear folder ownership, lint-enforced boundaries and fast CI usually delivers the benefits without the run-time complexity.

08Shared dependencies and version negotiation

Module Federation's share scope is a run-time registry where each loaded build registers the shared packages it brings, with versions. When a module needs React, the runtime picks a version that satisfies requiredVersion, preferring the highest available, and singleton: true forces exactly one instance, which React, React DOM, routers and context-based libraries require, because two copies break hooks and context. If no compatible version exists, a singleton logs a warning and uses the loaded one anyway, which can cause subtle bugs; strictVersion turns that into an error. eager: true bundles a shared module into the initial chunk, which avoids an async boundary but increases size. The usual pattern is an async bootstrap: the entry file does import('./bootstrap') so shared modules can be negotiated before the app starts.

1// src/index.ts  (entry)
2import("./bootstrap");
3 
4// src/bootstrap.tsx
5import { createRoot } from "react-dom/client";
6import { App } from "./App";
7createRoot(document.getElementById("root")!).render(<App />);
8 
9// shared config with strict checks for critical libs
10// shared: {
11//   react: { singleton: true, requiredVersion: "^19.0.0", strictVersion: true },
12//   "@acme/design-system": { singleton: true, requiredVersion: "^4.2.0" },
13// }

09Deployment, discovery and rollbacks

Independent deployment needs a way for the shell to find the current version of each remote. Hard-coding URLs in the shell's build couples deploys. Better: each remote publishes immutable, versioned assets (product/1.14.2/mf-manifest.json) to a CDN, and a small discovery document or service maps remote names to the active version per environment. The shell reads it at startup, or Module Federation's runtime plugins resolve remotes dynamically. Rolling back means pointing the map to the previous version, without rebuilding anything. This also enables canary releases and per-user overrides for testing. Cache the discovery document briefly, and give assets long cache lifetimes because their paths are versioned.

1// remotes.json served by a config endpoint (short cache)
2{
3  "product":  "https://cdn.example.com/product/1.14.2/mf-manifest.json",
4  "checkout": "https://cdn.example.com/checkout/3.2.0/mf-manifest.json"
5}
6 
7// shell bootstrap with the MF runtime
8import { init } from "@module-federation/enhanced/runtime";
9const remotes = await (await fetch("/config/remotes.json")).json();
10init({
11  name: "shell",
12  remotes: Object.entries(remotes).map(([name, entry]) => ({ name, entry: entry as string })),
13});

10Isolation: CSS, globals and failures

Run-time composition puts several teams' code in the same document, so isolation must be designed. CSS: global selectors from one remote can restyle another; use CSS Modules or a framework's scoped styles, prefix any global classes, and keep resets in the shell only. Web Components with Shadow DOM give hard style boundaries, at the cost of harder theming (use CSS custom properties, which pierce the shadow boundary). JavaScript globals: never patch window or prototypes in a remote, and namespace any storage keys. Failures: an error boundary per remote, timeouts on remote loading, and fallback UI keep the page usable. Tag errors and performance metrics with the remote name and version so on-call engineers know which team to page.

11Server-side composition and SSR

Client-side federation works for apps behind login, but public pages need fast first paint and SEO. Options: route-level server apps behind one domain (Next.js Multi-Zones or a reverse proxy routing /checkout to one app and /blog to another), which is simple and robust but means full page loads between zones; edge or server composition of HTML fragments, where a layout service fetches fragments from each team in parallel and streams them; or federated SSR, where Module Federation loads remote modules on the Node.js server too, which is powerful but complex to operate, with server-side caching and memory concerns. For most public sites, route-level zones plus a shared design system and header package is the pragmatic answer.

1# nginx: route-level composition under one domain
2location /checkout/ { proxy_pass http://127.0.0.1:3002; }
3location /account/  { proxy_pass http://127.0.0.1:3003; }
4location /          { proxy_pass http://127.0.0.1:3001; }  # main shop