Import Maps for Micro-Frontends and Shared React
On this page
The problem import maps solve
The shell wants to write import('@shop/cart') and get whatever version of the cart is live today. Browsers can import ES modules natively, but only by URL. A bare name like @shop/cart, or react, means nothing to them.
An import map is a small JSON block in the page that tells the browser what bare names mean:
<class="tok-k">script type="importmap">
{
"imports": {
"react": "/vendor/react-19.3.1.js",
"react-dom/client": "/vendor/react-dom-client-19.3.1.js",
"react/jsx-runtime": "/vendor/react-jsx-runtime-19.3.1.js",
"@shop/catalog": "/catalog/catalog.ICYQO7MU.js",
"@shop/cart": "/cart/cart.3TEMG4IL.js",
"@shop/header": "/header/header.74VIFCCW.js",
"@shop/account": "/account/account.UOVBVNB6.js"
}
}
</class="tok-k">script>
<class="tok-k">script type="module" src="/shell.js"></class="tok-k">script>Import maps work in all current browsers. The map must come before any module script that relies on it.
Two kinds of entries live in this map. The @shop/* names point at each team's latest build. The react names point at one shared copy of React, which every micro-frontend uses.
Build each micro-frontend separately
Each team builds its own code into an ES module and marks shared libraries as external, so the bundler leaves import ... from 'react' in the output instead of copying React in. Here's the build with esbuild, which every team runs in its own pipeline:
// build.mjs, run by the cart team
import { build } from 'esbuild';
await build({
entryPoints: ['src/cart/index.tsx'],
bundle: true,
format: 'esm',
jsx: 'automatic',
minify: true,
outdir: 'dist/cart',
entryNames: 'cart.[hash]', // content hash in the file name
external: ['react', 'react-dom/client', 'react/jsx-runtime'], // resolved by the import map
});The difference in size is dramatic. In the lab, each micro-frontend came out tiny because React wasn't inside it:
@shop/catalog 772 bytes
@shop/cart 1295 bytes
@shop/header 624 bytes
@shop/account 458 bytesThe shared React files, built once, total about 225 KB (70 KB gzipped). Without the import map, *each* React micro-frontend would carry its own copy of roughly that size.
Vite, Rspack and other bundlers can do the same with their own external settings, as long as the output is ES modules.
Build the shared React once
React is published as CommonJS, so it has to be turned into browser ES modules once, by whoever owns the shell. One subtle requirement: react-dom/client and react/jsx-runtime must use the *same* React instance, not each bundle their own. Building the three entry points together with code splitting does that:
await build({
entryPoints: ['vendor/react.js', 'vendor/react-dom-client.js', 'vendor/react-jsx-runtime.js'],
bundle: true, format: 'esm', splitting: true, minify: true,
outdir: 'dist/vendor', entryNames: '[name]-19.3.1',
define: { 'process.env.NODE_ENV': '"production"' },
});
// output: react-19.3.1.js, react-dom-client-19.3.1.js, react-jsx-runtime-19.3.1.js and shared chunksEach vendor/*.js file re-exports its package with an explicit list of names, generated by a small script:
// vendor/react.js (generated: the list comes from Object.keys(require('react')))
import * as m from 'react';
export const { Children, Component, Fragment, useState, useEffect, /* ...every other export */ } = m;
export default m;Why not just export * from 'react'? Browsers need ES module export names to be known statically, and React is CommonJS, so its names only exist at run time. In the lab, the export * version built without complaint, then failed in the browser with The requested module 'react' does not provide an export named 'useState'. The explicit list fixed it. The shared chunk holds React itself, so all three entry points use one instance. Many teams skip this step and point the map at a CDN that serves ES module builds, such as esm.sh. That's simpler, at the cost of depending on a third party for every page load.
What the browser actually loads
Loading the cart page in the lab fetched exactly these JavaScript files:
/shell.js
/header/header.74VIFCCW.js
/cart/cart.3TEMG4IL.js
/vendor/react-19.3.1.js
/vendor/react-dom-client-19.3.1.js
/vendor/react-jsx-runtime-19.3.1.js
/vendor/chunk-*.js (2 files)The catalog's file was only fetched when the user navigated to the catalog. React was fetched once, though three micro-frontends use it. The header's cart count went from 0 to 3 as items were added, the URL changed between / and /cart, and the back button worked. No console errors.
Cache hashed files forever
Every team file has a content hash in its name, like cart.3TEMG4IL.js. If the code changes, the name changes. That means those files can be cached for a year:
/cart/cart.3TEMG4IL.js cache-control: public, max-age=31536000, immutable
/vendor/react-19.3.1.js cache-control: public, max-age=31536000, immutable
/shell.js, the HTML page cache-control: no-cacheThe page and its import map must be revalidated on every load (no-cache), because the map is what tells the browser which version is live. Day 13 builds deployment and rollback on exactly this property: deploying a new cart means changing one line in the map.
Limits to know
- Set the map up front. The map has to be in place before the first module loads. Newer browsers let a page add further maps later, but a name the page has already resolved can't be pointed somewhere else, so a version change takes effect on the next page load.
- Scopes for exceptions. If one micro-frontend truly needs a different version of a library, the map's
scopesfield can give it one, as in"scopes": { "/legacy/": { "react": "/vendor/react-18.3.1.js" } }. Use it sparingly. Day 9 explains why two Reacts on a page cause trouble. - No TypeScript at run time. The browser loads plain JavaScript, so each team still needs a build step. Types for the contract come from the shared
@shop/contractpackage.
Check yourself
It tells the browser which URL a bare module name, like react or @shop/cart, refers to. Code can then import by name, and the page decides which version each name points to. That's what makes one-line deploys possible: changing an entry changes what every page loads next.
So the bundler leaves import ... from 'react' in the output instead of copying React into the bundle. The import map then resolves every micro-frontend's react to one shared copy. In the lab that kept each micro-frontend under 1.3 KB, while a copy that bundled React weighed about 224 KB.
A hashed file's content never changes, because new code gets a new name. The page holds the import map that says which hashed files are current, so it must be checked on every load.
The shared React file was built with export * from 'react'. React is CommonJS, so its export names only exist at run time, and browsers need ES module names to be known statically. Rebuild the vendor file with an explicit list of named exports, as the lesson's script generates.
File names contain content hashes like cart.3TEMG4IL.js. One typo in a hand-edited map breaks a whole area of the site for every user. Generating the map from each build's real output, and letting each pipeline update only its own entry, removes that class of mistake.