Catalog My learning Blog
Micro-Frontends Course: React, Import Maps and Teams · Phase 2 · Lesson 4 · 5 min read

The Micro-Frontend Mount Contract

On this page
  1. Why a contract comes first
  2. The contract in code
  3. A React micro-frontend
  4. A micro-frontend without a framework
  5. How the shell uses it
  6. Version the contract like an API
  7. Check yourself

Why a contract comes first

In client-side composition, a shell loads in the browser and brings in each team's code. The shell can't know how the cart team builds their UI. Maybe it's React 19, maybe plain TypeScript, maybe something else next year. What it can know is a contract: "every micro-frontend exports a function with this exact shape".

Get the contract right and teams can change almost everything behind it without telling anyone. Get it wrong, or leave it implicit, and every change becomes a cross-team negotiation.

The contract in code

Here's the contract for the shop used throughout this course. It's small on purpose:

Shell
// contract.ts, shared by the shell and every micro-frontend
export type MountProps = {
  basePath: string;                    // the URL prefix this micro-frontend owns, like "/cart"
  currency: string;                    // shell-level settings the micro-frontend needs
  navigate: (to: string) => void;      // ask the shell to change the URL
};
export type Unmount = () => void;
export type Mount = (el: HTMLElement, props: MountProps) => Unmount;

Three rules come with it:

  1. Render only inside el. A micro-frontend never touches DOM outside the element it was given.
  2. Clean up everything in Unmount. DOM, event listeners, timers, subscriptions. After unmount it should be as if the micro-frontend was never there.
  3. Props are the only input from the shell. No reaching into globals the shell happens to set.

A React micro-frontend

The catalog team uses React. Their whole integration with the shell is a dozen lines:

JavaScript
// catalog/index.tsx
import { createRoot } from 'react-dom/client';
import type { Mount } from '../contract';
import { Catalog } from './Catalog';

export const mount: Mount = (el, props) => {
  const root = createRoot(el);
  root.render(<Catalog currency={props.currency} />);
  return () => root.unmount();
};

Each micro-frontend gets its own React root. That's what makes them independent: the catalog's state, effects and errors live inside its root and nowhere else. React's root.unmount() runs every effect cleanup inside it, which takes care of rule 2 for React code.

A micro-frontend without a framework

The header team chose plain TypeScript, because a header with three links doesn't need a framework. The contract is the same:

TypeScript
// header/index.ts
import type { Mount } from '../contract';

export const mount: Mount = (el, props) => {
  el.innerHTML = `<header><a href="/" data-link>Shop</a> | <a href="/cart" data-link>Cart</a></header>`;

  const onClick = (e: Event) => {
    const a = (e.target as HTMLElement).closest('a[data-link]');
    if (a) {
      e.preventDefault();
      props.navigate(a.getAttribute('href')!);   // let the shell own the URL
    }
  };
  el.addEventListener('click', onClick);

  return () => {
    el.removeEventListener('click', onClick);
    el.innerHTML = '';
  };
};

Notice props.navigate. The header doesn't call history.pushState itself. The shell owns top-level navigation (Day 6), and the contract gives micro-frontends a polite way to ask for it.

How the shell uses it

The shell's side is just as small. Load a module, call mount, keep the returned function:

TypeScript
let current: { app: string; unmount: Unmount } | null = null;

async function show(app: string, basePath: string) {
  current?.unmount();
  const el = document.createElement('div');
  outlet.replaceChildren(el);
  const mod: { mount: Mount } = await import(app);
  current = { app, unmount: mod.mount(el, { basePath, currency: 'USD', navigate }) };
}

Where does import(app) load the code from? That's tomorrow's topic: import maps. For now, what matters is that the shell treats every micro-frontend the same way, whatever it's built with.

Version the contract like an API

The contract is a public API between teams, so treat it like one:

  • Keep it in a small package, like @shop/contract, with types only, and version it with semantic versioning.
  • Add optional props freely. Remove or change props only with a major version and a migration window, because the shell and every micro-frontend deploy separately.
  • Write it down: one page that lists the props, the rules and the events (Day 8).

Resist the urge to grow the contract into a framework. When teams ask for "just one more shared thing", like a global store or a shared HTTP client, ask whether it could be a normal library each team installs instead. The contract should stay small enough to read in a minute.

TipGive each micro-frontend a standalone dev page that mounts it with fake props. Teams can then work without running the shell, and the dev page doubles as the contract's first test.

Check yourself

A separate root keeps each micro-frontend's state, effects and errors isolated from the others, and lets them run different React setups. When the shell removes it, root.unmount() runs every effect cleanup inside it. And if a render error goes uncaught, React removes only that root, leaving other teams' areas working.

The shell owns top-level routing, so it needs to know when the URL changes in order to swap the active micro-frontend. If the header called history.pushState itself, the URL would change but the shell wouldn't render the new page. Going through navigate keeps the URL and the shell in sync.

As a contract change: add currencyCode as a new optional prop, update the shell to send both, move micro-frontends over, and only then remove currency in a new major version.

Every visit to that area adds another listener that's never removed. Memory use and work per resize grow over the session, and old listeners may run against DOM that no longer exists, causing errors. The unmount function must remove everything mount adds.

It creates a hidden dependency outside the contract. The shell team doesn't know anyone relies on that global, so a harmless refactor breaks another team silently. If micro-frontends need the user, add it to MountProps, where it's typed, documented and versioned.