Independent Micro-Frontend Deploys and Rollback
On this page
What "independent" has to mean
A team can deploy independently when three things are true:
- They can release without asking another team, and without a shell release.
- A bad release can be undone in seconds, without a rebuild.
- Releasing never breaks users who already have the page open.
The import map gives you most of this almost for free, if you set up the pieces carefully.
Step 1: Publish immutable, hashed files
Each team's pipeline builds its micro-frontend into a file named after its content, like cart.7DR5UG3B.js, and uploads it to shared static storage, such as an S3 bucket or similar behind a CDN, under the team's own folder:
/cart/cart.3TEMG4IL.js (yesterday)
/cart/cart.7DR5UG3B.js (today)The file is never changed and never overwritten. It's served with cache-control: public, max-age=31536000, immutable, so browsers and the CDN keep it for a year.
Don't delete old files right away. A user who opened the shop yesterday still has yesterday's import map in their tab, and their next lazy import('@shop/cart') asks for cart.3TEMG4IL.js. Delete it and that user's cart breaks. Keep old versions for weeks, or for as long as a tab could plausibly stay open, and clean up with a lifecycle rule.
Step 2: Serve the import map from one place
The map says which file is live for each name. Keep it as data, not code, and serve it fresh on every page load:
// shell server: inject the current map into the page on every request
app.setNotFoundHandler((req, reply) => {
const map = fs.readFileSync('current-importmap.json', 'utf8'); // or a key-value store
reply.header('cache-control', 'no-cache').type('text/html').send(`<!doctype html>
<html><head>
<script type="importmap">${map}</script>
<script type="module" src="/shell.js"></script>
</head><body><div id="header"></div><main id="outlet"></main></body></html>`);
});In production, keep the map in a small service or a key-value store. Each team's pipeline may change only its own entry, after its tests pass. That permission boundary matters: it's what makes the cart team's deploy unable to break the catalog.
Step 3: Deploy by changing one line
A cart deploy is now just this:
- "@shop/cart": "/cart/cart.3TEMG4IL.js",
+ "@shop/cart": "/cart/cart.7DR5UG3B.js",The lab did exactly that and reloaded the cart page:
v1 | Your cart
after deploying cart v2 | Your basket
after rollback to v1 | Your cartThe header, catalog and React entries kept exactly the same file names, so browsers can keep using the copies already in their cache. Only the cart's file was new.
Rollback is the same one-line change in reverse. No rebuild, no waiting for a pipeline. Keep the previous value of each entry so a rollback is a single button.
Step 4: Roll out gradually
Because the map is generated per request, you can serve different maps to different users:
- Canary: send 5% of users the new cart, watch error rates for those sessions (Day 14), then go to 100%.
- Internal first: staff see the new version for a day before customers.
- Per-team preview URLs: a pull request's preview map replaces one entry, for testing (Day 12).
Choose the bucket from something stable, like a hash of the session id, so a user doesn't flip between versions on every page load.
Step 5: Handle version skew
During any rollout, different users run different combinations, and one user's open tab can mix old and new: an old shell and map, plus whatever was loaded lazily. Keep it safe with the rules you already know:
- Contract and event changes are additive (Days 4 and 8), so old and new versions understand each other.
- Old files stay available, so old tabs keep working.
- For a change that truly can't mix, have the shell check a version endpoint on navigation and reload the page when the map is too old.
A deploy that fails
The lab also pointed the cart entry at a file that didn't exist, which is what a botched upload looks like:
cart file missing | This section is unavailable right now. Please try again later.
catalog still works with cart broken: Added Desk lampThe shell's error handling (Day 6) kept the damage to one section. The team's pipeline should still catch it before users do. After updating the map, request the new file and a smoke-test page, and roll back automatically if either fails.
Check yourself
Users with the page already open still have the old import map, and their next lazy import asks for the old file. Deleting it breaks their session.
Point the cart's import map entry back at the previous hashed file. The old file is still in storage, so nothing needs rebuilding, and the change takes effect on the next page load. Keep each entry's previous value so a rollback is a single action.
So one team's deploy, or mistake, can't change which version of another team's micro-frontend is live. That permission boundary is what makes independent deployment safe: the worst a bad cart deploy can do is break the cart, and it can be rolled back without touching anyone else.
Generate the import map per request and choose the cart entry by a stable bucket, such as a hash of the session id, so each user consistently sees one version. Watch error rates for the canary sessions, then move everyone over or roll back.
After updating the map, request the new file and a smoke-test page that mounts the micro-frontend, and roll the entry back automatically if either fails. The shell's error handling limits the damage, but the pipeline should never leave a broken entry live.