Catalog My learning Blog
Micro-Frontends Course: React, Import Maps and Teams · Phase 3 · Lesson 9 · 6 min read

Sharing React Across Micro-Frontends Safely

On this page
  1. The size problem
  2. The correctness problem
  3. Decide what to share
  4. Version policy for shared libraries
  5. Upgrading a major version without a big bang
  6. Tools that automate sharing
  7. Check yourself

The size problem

Each React micro-frontend that bundles its own React carries the whole library. The lab built the same small component two ways:

Code
micro-frontend using the shared React (import map):   772 bytes
micro-frontend bundling its own React:                 223,818 bytes (69 KB gzipped)

Five teams each bundling React means five copies on one page: about 350 KB of compressed JavaScript that does the same thing five times, plus the time to parse and run it. That's why Day 5 shared one copy through the import map.

The correctness problem

Size is the visible cost. The hidden one is that two copies of React don't know about each other. In the lab, a micro-frontend with its own React rendered fine on its own:

Code
own copy alone:  Own React 19.3.1: 1    (clicks work, state updates)

Then it rendered a MiniCart component exported by another team, which was built against the *shared* React and uses useState. The page crashed:

Code
Minified React error #321   (Invalid hook call)

Hooks rely on the React instance that's rendering. MiniCart called useState from copy A while copy B was rendering it, so copy A had no idea which component was active. The same thing happens with context: a ThemeProvider from one copy is invisible to components using another copy.

The rule that follows:

  • Two React copies on one page are survivable if each micro-frontend renders only its own components in its own root, and they communicate through events and the DOM, never by passing components or context across.
  • They break the moment components, hooks or context cross the boundary.

This is one of the strongest arguments for the mount contract from Day 4: it never passes React components between teams, only DOM elements and plain props.

Decide what to share

Not every dependency should be shared. Share a library when all of these hold:

  • it's large, or several teams use it,
  • it holds state that must be single, like React or a router that owns history,
  • teams can agree on one version and upgrade together a few times a year.

Good candidates: React and React DOM, the design system's component library (Day 10), and the contract package with event types.

Don't share small utilities (date formatting, a debounce helper) or anything one team uses. Bundling them costs a few kilobytes and buys full independence. Sharing them means every upgrade needs every team.

Version policy for shared libraries

When React is shared through the import map, the shell owner decides which version is on the page. Every team must build and test against it. Write the policy down:

  1. The platform team owns the shared versions, listed in one place.
  2. Teams build against the same major version, enforced in CI by checking each team's package.json against the shared list.
  3. Minor and patch upgrades of the shared copy are rolled out by the platform team after the teams' test suites pass against it.
  4. Major upgrades follow a plan with a deadline.

React's own policy helps: within a major version, the API stays backward compatible, so one shared 19.x copy serves components built against any earlier 19.x.

Upgrading a major version without a big bang

Sooner or later React 20 arrives, and five teams can't all upgrade on the same day. The import map's scopes let two versions coexist during the migration:

JSON
{
  "imports": {
    "react": "/vendor/react-19.3.1.js",
    "@shop/cart": "/cart/cart.8KD2LQ1M.js"
  },
  "scopes": {
    "/cart/": {
      "react": "/vendor/react-20.0.0.js",
      "react-dom/client": "/vendor/react-dom-client-20.0.0.js"
    }
  }
}

Modules loaded from /cart/ now get React 20. Everyone else stays on 19. The lab tested the same mechanism with React 18 as the odd one out: the cart page reported React 18.3.1, the rest of the page reported 19.3.1, and the "item added" events still moved the header's count, with no errors. This works safely *because* the mount contract never passes components across the boundary, which is exactly the "survivable" case above. Once every team has moved, React 20 becomes the default and the scope is removed. Expect a page with both versions to be heavier until the migration ends, so keep the window short.

Tools that automate sharing

If you use Module Federation through webpack, Rspack, Vite or another supported bundler, it handles shared dependencies for you. Each build declares which libraries it shares and which versions it accepts, a library can be marked as a singleton, and at run time it loads one compatible copy and warns when a version requirement isn't met. The ideas are the same as in this lesson: one copy of stateful libraries, an agreed version range, and a plan for when ranges don't overlap. A tool makes it convenient, but it doesn't remove the need for a policy.

TipAdd a check to the shell in development that reads React.version from each micro-frontend's mount (have the contract return it) and warns if more than one version is on the page. It turns a crash in production into a warning in development.

Check yourself

Yes, as long as each renders only its own components in its own root and they talk through events and props, never by passing components or context. The cost is size: in the lab, a micro-frontend that bundled React was about 69 KB gzipped, against 772 bytes when it used the shared copy.

A component using hooks is being rendered by a different React copy than the one it imports, typically because a component was passed across a micro-frontend boundary.

Usually not. It's small and stateless, so bundling a copy in each micro-frontend costs a few kilobytes and lets each team upgrade on its own schedule. Sharing it would make every upgrade a cross-team event, which is only worth it for large or stateful libraries like React.

It's safe because the mount contract never passes components, hooks or context between micro-frontends, so each React copy only renders its own tree. The lab confirmed it: the cart reported React 18.3.1, the page 19.3.1, and events still worked. It would break the moment a component from one copy rendered inside the other's tree.

Have the shell report each micro-frontend's React version in development, for example by returning React.version from mount, and warn when more than one appears. Add a bundle-size budget in CI too, since a bundled React adds about 69 KB gzipped and trips the budget immediately.