Micro-Frontends Architecture

Micro-frontends apply the principles of microservices to the frontend: independent teams own independent slices of the UI, deploying independently, with independent technology choices. It's a powerful pattern — and a dangerous one if adopted without understanding the costs.

Why Micro-Frontends?

┌─────────────────────────────────────────────────────────┐
│                    Monolith Frontend                     │
│                                                         │
│  Team A       Team B       Team C       Team D          │
│  ─────────────────────────────────────────────          │
│  All teams commit to the same repo                      │
│  All teams deploy together                              │
│  Merge conflicts, coordination overhead, slow CI        │
│  One bad deploy = everything broken                     │
└─────────────────────────────────────────────────────────┘
 
                        ▼ Scale pain ▼
 
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│  Team A  │  │  Team B  │  │  Team C  │  │  Team D  │
│ Catalog  │  │  Cart    │  │ Checkout │  │ Account  │
│          │  │          │  │          │  │          │
│ Own repo │  │ Own repo │  │ Own repo │  │ Own repo │
│ Own CI   │  │ Own CI   │  │ Own CI   │  │ Own CI   │
│ Own deploy│ │ Own deploy│ │ Own deploy│ │ Own deploy│
└──────────┘  └──────────┘  └──────────┘  └──────────┘

The Three Drivers

Team autonomy: Teams can choose their own tools, frameworks, and release cadence
Independent deployments: Ship the cart without waiting for catalog to finish their feature
Technology heterogeneity: Team A uses React, Team C uses Vue — both coexist

Composition Patterns

Build-Time Composition

Micro-frontends are npm packages consumed by a host application at build time.

┌──────────────┐
│  Host App    │
│              │     npm install
│  imports:    │◀──────────────── @org/catalog-mfe
│  @org/cart   │◀──────────────── @org/cart-mfe
│  @org/acct   │◀──────────────── @org/account-mfe
│              │
│  Webpack     │──── Single bundle ────▶ Deploy
└──────────────┘

Pros: Simple, good tree-shaking, type safety across boundaries Cons: All teams must deploy together (defeats the purpose), version lock-in

Runtime Composition via Module Federation

The dominant pattern for production micro-frontends:

┌──────────────────────────────────────────────────┐
│                    Host Shell                      │
│  ┌────────────────────────────────────────────┐  │
│  │  Header (shared)                            │  │
│  ├────────────────────────────────────────────┤  │
│  │         ┌─────────────────────────┐        │  │
│  │  Nav    │    Remote Module        │        │  │
│  │  bar    │    (loaded at runtime)  │        │  │
│  │         │                         │        │  │
│  │         │  /catalog → catalog-mfe │        │  │
│  │         │  /cart    → cart-mfe    │        │  │
│  │         │  /account → account-mfe │        │  │
│  │         └─────────────────────────┘        │  │
│  ├────────────────────────────────────────────┤  │
│  │  Footer (shared)                            │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Iframe Composition

<iframe src="https://catalog.example.com" title="Product Catalog" />

Pros: Perfect isolation (CSS, JS, security) Cons: No shared state, poor UX (no shared scroll, routing), accessibility nightmare, performance overhead

Edge-Side Includes (ESI)

Server-side composition at the CDN/edge layer:

<header>
  <esi:include src="https://header.example.com/fragment" />
</header>
<main>
  <esi:include src="https://catalog.example.com/fragment" />
</main>

Pros: Works without JavaScript, fast TTFB Cons: Limited interactivity, CDN support varies

Module Federation 2.0 Deep Dive

Module Federation is Webpack's (and now Rspack's) native solution for sharing code between independently built applications at runtime.

Host Configuration

// shell/webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
 
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'shell',
      remotes: {
        catalog: 'catalog@https://catalog.example.com/remoteEntry.js',
        cart: 'cart@https://cart.example.com/remoteEntry.js',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
        'react-router-dom': { singleton: true },
      },
    }),
  ],
};

Remote Configuration

// catalog/webpack.config.js
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'catalog',
      filename: 'remoteEntry.js',
      exposes: {
        './CatalogPage': './src/CatalogPage',
        './ProductCard': './src/components/ProductCard',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
};

Loading Remote Modules

const CatalogPage = React.lazy(() => import('catalog/CatalogPage'));
 
function App() {
  return (
    <Routes>
      <Route
        path="/catalog/*"
        element={
          <Suspense fallback={<PageSkeleton />}>
            <ErrorBoundary fallback={<RemoteLoadError />}>
              <CatalogPage />
            </ErrorBoundary>
          </Suspense>
        }
      />
    </Routes>
  );
}

Module Federation 2.0 Improvements

Runtime API: Dynamic remote registration without rebuild
Manifest protocol: Standardized remote discovery
Type hints: Shared TypeScript types across remotes
Version negotiation: Smarter shared dependency resolution

Shared Dependencies Strategy

The biggest challenge: how do you avoid loading React 5 times?

┌──────────────────────────────────────────────────┐
│              Shared Dependency Strategy            │
│                                                  │
│  Singleton (one version loaded)                  │
│  ├─ react, react-dom                            │
│  ├─ react-router-dom                            │
│  └─ design-system                               │
│                                                  │
│  Scoped (each MFE has its own)                   │
│  ├─ form libraries                              │
│  ├─ date libraries                              │
│  └─ MFE-specific utilities                      │
│                                                  │
│  Externalized (loaded from CDN)                  │
│  └─ Large libraries loaded once via importmap   │
└──────────────────────────────────────────────────┘

{
  "imports": {
    "react": "https://cdn.example.com/react@18/esm/index.js",
    "react-dom": "https://cdn.example.com/react-dom@18/esm/index.js"
  }
}

Routing Across Micro-Frontends

Shell-Owned Routing

Shell Router (top-level routes)
  │
  ├─ /catalog/*  → Catalog MFE (owns sub-routes)
  │   ├─ /catalog/
  │   ├─ /catalog/:id
  │   └─ /catalog/category/:slug
  │
  ├─ /cart/*     → Cart MFE
  │   ├─ /cart/
  │   └─ /cart/checkout
  │
  └─ /account/*  → Account MFE
      ├─ /account/profile
      └─ /account/orders

The contract: The shell owns top-level routes. Each MFE owns its sub-routes. Navigation between MFEs goes through the shell's router. Navigation within an MFE uses its own router.

// Shell routes
<Routes>
  <Route path="/catalog/*" element={<CatalogMFE />} />
  <Route path="/cart/*" element={<CartMFE />} />
  <Route path="/account/*" element={<AccountMFE />} />
</Routes>
 
// Inside Catalog MFE — uses MemoryRouter or basename
<Routes>
  <Route index element={<CatalogList />} />
  <Route path=":id" element={<ProductDetail />} />
</Routes>

Shared State & Communication

Micro-frontends should be loosely coupled. Communication should be through well-defined interfaces, not shared state stores.

Custom Events (Recommended)

// Cart MFE dispatches
window.dispatchEvent(new CustomEvent('cart:updated', {
  detail: { itemCount: 3, total: 59.97 },
}));
 
// Header MFE listens
useEffect(() => {
  const handler = (e: CustomEvent) => setCartCount(e.detail.itemCount);
  window.addEventListener('cart:updated', handler);
  return () => window.removeEventListener('cart:updated', handler);
}, []);

URL State (Simplest)

/catalog?search=shoes&sort=price
 
Every MFE can read URL params. No shared runtime needed.

Shared Event Bus (Typed)

type EventMap = {
  'cart:updated': { itemCount: number; total: number };
  'user:logout': undefined;
  'notification:new': { message: string; type: 'info' | 'error' };
};
 
class EventBus {
  private handlers = new Map<string, Set<Function>>();
 
  emit<K extends keyof EventMap>(event: K, data: EventMap[K]) {
    this.handlers.get(event)?.forEach(handler => handler(data));
  }
 
  on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void) {
    if (!this.handlers.has(event)) this.handlers.set(event, new Set());
    this.handlers.get(event)!.add(handler);
    return () => this.handlers.get(event)?.delete(handler);
  }
}
 
export const eventBus = new EventBus();

CSS Isolation

Without isolation, one MFE's .button class clobbers another's.

Strategy	Isolation Level	Trade-off
CSS Modules	File-scoped	Build tool required
Shadow DOM	Full encapsulation	Style sharing is harder
CSS-in-JS	Runtime scoped	Runtime cost, SSR complexity
BEM / Prefixing	Convention-based	Relies on discipline
CSS Layers	Cascade control	Modern browsers only

/* Using CSS Layers for MFE isolation */
@layer shell, catalog, cart, account;
 
@layer catalog {
  .product-card { /* only within catalog layer */ }
}
 
@layer cart {
  .product-card { /* different styles, no conflict */ }
}

Testing Strategies

┌────────────────────────────────────────────────┐
│              Testing Pyramid for MFEs           │
│                                                │
│           ▲                                    │
│          ╱ ╲    E2E (full integration)         │
│         ╱───╲   All MFEs composed in shell     │
│        ╱ Ctr ╲  Contract tests                 │
│       ╱───────╲ Verify MFE ↔ Shell interface   │
│      ╱  Int    ╲ Integration within each MFE   │
│     ╱───────────╲                              │
│    ╱    Unit     ╲ Components, hooks, utils    │
│   ╱───────────────╲                            │
└────────────────────────────────────────────────┘

Contract tests are critical: they verify that the shell and remotes agree on the interface (exported components, props, events) without requiring full integration.

When NOT to Use Micro-Frontends

Signal	Reality
"It's what Netflix does"	Netflix has 1000+ frontend engineers. You have 12.
One team, one app	You're adding complexity without the organizational benefit
Premature optimization	Start monolithic, extract when pain is real
Tech diversity for fun	Consistency > novelty for maintainability
< 3 teams	The coordination cost exceeds the independence benefit

The Complexity Cost

Monolith:  1 repo, 1 build, 1 deploy, 1 test suite
MFE:       N repos, N builds, N deploys, N+1 test suites,
           shared deps management, cross-MFE routing,
           CSS isolation, communication protocol,
           deployment orchestration, monitoring per MFE

Monorepo vs Polyrepo

Factor	Monorepo	Polyrepo
Code sharing	Easy (workspace imports)	Hard (publish packages)
Consistency	Enforced (shared config)	Varies per repo
CI/CD	Complex (affected-only builds)	Simple per repo
Tooling	Turborepo, Nx, Lerna	Standard per-repo tooling
Autonomy	Lower (shared conventions)	Higher (full independence)
Onboarding	One clone	N clones

Recommended: Monorepo with Module Federation

monorepo/
  apps/
    shell/          ← Host application
    catalog/        ← Remote MFE
    cart/           ← Remote MFE
    account/        ← Remote MFE
  packages/
    design-system/  ← Shared UI components
    shared-types/   ← TypeScript interfaces
    event-bus/      ← Communication layer
    eslint-config/  ← Shared linting rules
  turbo.json        ← Build orchestration

This gives you the organizational benefits of micro-frontends (independent builds, independent deploys) with the developer experience of a monorepo (shared types, easy refactoring, consistent tooling).

Deployment Pipeline

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Commit  │───▶│  Build   │───▶│  Test    │───▶│  Deploy  │
│          │    │  MFE     │    │  Unit +  │    │  to CDN  │
│  (cart)  │    │  only    │    │ Contract │    │  (cart)  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                     │
                                                     ▼
                                              ┌──────────┐
                                              │ Smoke    │
                                              │ Test in  │
                                              │ Staging  │
                                              │ (full    │
                                              │  shell)  │
                                              └──────────┘

Each MFE deploys independently. The shell loads the latest version of each remote at runtime. No coordinated releases needed.

Micro-frontends are an organizational scaling pattern, not a technical optimization. Use them when you have the team structure that demands them. Don't use them because they're architecturally interesting. That's the architect's judgment call.