Micro-Frontend Architecture & Federation Guide

Decoupling Frontend Teams Without Sacrificing UX #

Independently deployable remotes give each team its own release cadence, but users still expect one coherent product — so the hard part is letting teams ship on their own schedule while the buttons, spacing, loading states, and navigation stay identical across every remote.

This guide walks through four concrete contracts that keep autonomy and visual coherence in balance: shared design tokens, a shell/layout contract the host owns, coordinated loading and skeleton states, and consistent navigation. Each step is a minimal, runnable snippet you can lift into a real host-and-remotes setup.

The work sits squarely inside managing cross-team coupling: you are deciding exactly what teams must agree on so they need to coordinate as little as possible everywhere else.

Prerequisites #

This guide assumes a host application that composes one or more remotes via Module Federation. The versions below are what the snippets are tested against.

Shared contracts that keep decoupled teams coherent A host shell at top distributes design tokens, a shell contract, and navigation events down to two independently deployed remotes. Host shell owns layout, nav, loading orchestration Design tokens CSS custom props Shell contract mount(props) Navigation router events Remote: Catalog team A · own deploy Remote: Checkout team B · own deploy
The host owns the shell; the three shared contracts are the only things every team must agree on.

Step 1 — Ship one source of design tokens #

Visual drift starts when each team hard-codes its own colors and spacing. Fix it by publishing tokens as a versioned package that emits CSS custom properties, so every surface resolves the same value at runtime even when teams are on slightly different package versions.

Define tokens once:

// tokens/color.json
{
  "color": {
    "brand": { "primary": { "value": "#0f77c7" } },
    "surface": { "raised": { "value": "#ffffff" } },
    "text": { "default": { "value": "#10324d" } }
  },
  "space": {
    "sm": { "value": "8px" },
    "md": { "value": "16px" }
  }
}

Build them into CSS custom properties with Style Dictionary:

// build-tokens.js
const StyleDictionary = require('style-dictionary');

StyleDictionary.extend({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }],
    },
  },
}).buildAllPlatforms();

The host loads tokens.css once at the document root. Remotes never import the raw values — they reference the variables, so a token change deploys without rebuilding every remote:

/* in any remote's component styles */
.checkout-button {
  background: var(--color-brand-primary);
  color: var(--color-surface-raised);
  padding: var(--space-sm) var(--space-md);
}

Step 2 — Define a shell/layout contract the host owns #

Decoupling fails when remotes each render their own page chrome. Instead, the host exposes a stable mount contract, and remotes export a mount/unmount pair that the host calls. The host controls layout slots; the remote only fills them.

Expose the contract from the remote:

// remote: src/bootstrap.ts
import type { Root } from 'react-dom/client';
import { createRoot } from 'react-dom/client';
import App from './App';

export interface MountProps {
  container: HTMLElement;
  basePath: string;
  onNavigate: (path: string) => void;
}

let root: Root | null = null;

export function mount({ container, basePath, onNavigate }: MountProps) {
  root = createRoot(container);
  root.render(<App basePath={basePath} onNavigate={onNavigate} />);
}

export function unmount() {
  root?.unmount();
  root = null;
}

The host renders the layout, hands the remote a single container node, and stays the owner of everything around it:

// host: src/RemoteSlot.tsx
import { useEffect, useRef } from 'react';

export function RemoteSlot({ load, basePath, onNavigate }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    let cleanup = () => {};
    load().then(({ mount, unmount }) => {
      mount({ container: ref.current!, basePath, onNavigate });
      cleanup = unmount;
    });
    return () => cleanup();
  }, [load, basePath, onNavigate]);

  return <div className="remote-slot" ref={ref} />;
}

Because the host passes basePath and onNavigate in, the remote never assumes where it lives — the same build drops into any layout slot.

Step 3 — Coordinate loading and skeleton states #

Independently loaded remotes resolve at different speeds, so without coordination the page flickers in piecemeal. The shell should reserve space and show a consistent skeleton that matches the final layout, eliminating layout shift while a remote streams in.

Drive loading through Suspense with a shared skeleton component the host owns:

// host: src/App.tsx
import { Suspense, lazy } from 'react';
import { PanelSkeleton } from '@acme/ui/skeletons';
import { RemoteSlot } from './RemoteSlot';

const loadCatalog = () => import('catalog/bootstrap');

export default function App() {
  return (
    <main className="app-grid">
      <Suspense fallback={<PanelSkeleton rows={4} />}>
        <RemoteSlot load={loadCatalog} basePath="/catalog" onNavigate={navigate} />
      </Suspense>
    </main>
  );
}

Reserve the skeleton’s footprint in CSS so the slot never collapses then jumps — this is what keeps Cumulative Layout Shift near zero:

.remote-slot {
  min-height: 320px;          /* matches the skeleton + typical content */
  contain: layout paint;       /* isolate remote reflow from the shell */
}

Build the skeleton from the same design tokens as the real component so the placeholder reads as part of the product, not a generic spinner:

// @acme/ui/skeletons/PanelSkeleton.tsx
export function PanelSkeleton({ rows = 3 }: { rows?: number }) {
  return (
    <div className="skeleton" aria-busy="true" aria-live="polite">
      {Array.from({ length: rows }).map((_, i) => (
        <div key={i} className="skeleton__row" style={{ background: 'var(--color-surface-raised)' }} />
      ))}
    </div>
  );
}

Step 4 — Keep navigation consistent across remotes #

If each remote calls history.pushState directly, the back button breaks and links between teams stop working. Route everything through one navigation contract: remotes emit intent, the host owns the router and broadcasts the result.

Have the host expose navigation as a small event-driven API. Remotes call onNavigate (passed in via the mount contract) instead of touching history themselves:

// host: src/navigation.ts
const subscribers = new Set<(path: string) => void>();

export function navigate(path: string) {
  if (window.location.pathname === path) return;
  window.history.pushState({}, '', path);
  subscribers.forEach((fn) => fn(path));
}

export function onRouteChange(fn: (path: string) => void) {
  subscribers.add(fn);
  const onPop = () => fn(window.location.pathname);
  window.addEventListener('popstate', onPop);
  return () => {
    subscribers.delete(fn);
    window.removeEventListener('popstate', onPop);
  };
}

Inside the remote, links call the injected callback so the host can keep its active-nav state, breadcrumbs, and analytics correct:

// remote: src/NavLink.tsx
export function NavLink({ to, onNavigate, children }) {
  return (
    <a
      href={to}
      onClick={(e) => {
        e.preventDefault();
        onNavigate(to);
      }}
    >
      {children}
    </a>
  );
}

When remotes need to react to each other (a checkout completing should refresh the cart badge), keep that traffic off the router and on a dedicated channel — the event bus patterns for decoupled apps cover that decoupled signalling without re-coupling teams.

Verification #

Confirm the four contracts hold before you call the boundary decoupled.

Troubleshooting #

Symptom: a remote renders with the wrong brand color or spacing.

Diagnosis: the remote is reading hard-coded values or a stale local token copy instead of the host’s CSS custom properties. Fix: remove any literal color/spacing from the remote’s styles, confirm the host loads tokens.css at the document root before remotes mount, and verify the custom property name matches exactly — a missing --color- prefix silently falls back to the inherited value.

Symptom: the page flickers or jumps as remotes load.

Diagnosis: the slot has no reserved height, so it collapses to zero before content arrives and reflows when it does. Fix: set min-height on .remote-slot to match the skeleton, add contain: layout paint, and make sure the Suspense fallback renders the same PanelSkeleton dimensions as the loaded component.

Symptom: the back button skips pages or the active nav item is wrong.

Diagnosis: a remote is calling history.pushState directly instead of the injected onNavigate, so the host never learns about the route change. Fix: route every in-remote link through the onNavigate prop from the mount contract, and ensure the host’s onRouteChange is the only place subscribing to popstate.

Symptom: hooks throw “Invalid hook call” after a remote mounts.

Diagnosis: two React copies are loaded because singleton: true is missing or the required versions don’t overlap. Fix: set react and react-dom to { singleton: true, requiredVersion } in every ModuleFederationPlugin config, and align the versions so a single instance satisfies all consumers.

← Back to Managing Cross-Team Coupling

Related content