Migrating MUI in a Single-SPA Microfrontend — What the Official Docs Don't Tell You

This article is the third in a series. The first two cover individual problems in detail: MUI v4/v5 Style Conflicts in single-spa — A Complete Debug Record and Static CSS Leakage in Microfrontends — Why Shadow DOM Fails and How postcss-prefix-selector Fixes It. This article connects the full picture.

This article documents the style conflicts encountered during a MUI v4 → v6 upgrade in a single-spa microfrontend — dynamic style conflicts, static CSS leakage, and what I learned about the limits of v4 JSS isolation and v6 Emotion isolation strategies after taking over child app upgrades.

---

Background

The project uses a single-spa microfrontend architecture. The host application is main-app, which loads child apps dynamically — including analytics-child-app, ai-child-app, calculator-child-app, and others.

Three things to understand upfront.

First, single-spa has no CSS isolation. It only isolates JavaScript scope. All child apps share the same document.head, so any <style> tag inserted by any child app affects the entire page.

Second, MUI v4 and v5/v6 use completely different style injection systems. v4 uses JSS — style tags it produces carry a data-jss attribute. v5/v6 switched to Emotion, which uses data-emotion.

Third, MUI semantic class names are identical across v4 and v5/v6. .MuiButtonBase-root exists in both versions. This is why conflicts happen — two engines inject different rules for the same class, and whichever inserts last wins.

---

Problem 1: Dynamic Style Conflicts

What happened

After main-app completed its MUI v4 → v5 migration, a status indicator on the Dashboard that should have been circular started turning square — but only after navigating away and back. The first load was always fine.

Debugging

Clue 1: data-jss style tags appearing and disappearing with route changes.

The tags weren't always present — they appeared when navigating back to Dashboard and disappeared when navigating away. The timing matched the indicator changing shape exactly.

Clue 2: MutationObserver to catch the insertion.

new MutationObserver((mutations) => {
  mutations.forEach(m => {
    m.addedNodes.forEach(node => {
      if (node.nodeName === 'STYLE' && node.dataset && node.dataset.jss !== undefined) {
        console.log('JSS style tag inserted:');
        console.log(node.textContent.substring(0, 500));
      }
    });
  });
}).observe(document.head, { childList: true });

The output contained component names including MuiToggleButtonGroup and MuiCircularProgress. At the same moment, a single-spa warning appeared: analyticsChildApp's rootComponent should implement componentDidCatch. The timing was identical. Suspicion locked onto analytics-child-app.

Clue 3: Fetch the bundle to confirm the MUI version.

fetch('/analytics-child-app/index.js')
  .then(r => r.text())
  .then(t => {
    const match = t.match(/@material-ui|@mui\/material/g);
    console.log('MUI references found:', [...new Set(match)]);
  });

Result: ['@material-ui']. Root cause confirmed — analytics-child-app's dev deployment was still running MUI v4.

Why the first load was fine

The first time Dashboard loads, analytics-child-app fetches its bundle asynchronously. While it's downloading, Emotion has already written its styles — JSS hasn't injected yet, so the indicator stays circular.

On the next visit, the bundle is cached. analytics-child-app mounts almost instantly, JSS injects immediately after Emotion's tags, and wins the cascade. The indicator turns square.

The first load was fine because of the download delay. Subsequent loads broke because caching eliminated that delay.

Fix

Re-deploy analytics-child-app from the updated master branch to the dev environment.

---

Problem 2: Static CSS Leakage

What happened

After fixing the dynamic conflict, another problem surfaced: static CSS files inside analytics-child-app — App.css, Table.css — contained hardcoded MUI semantic class names like .MuiTypography-body1, which were leaking into and affecting the host app.

Why Shadow DOM doesn't work

A colleague suggested using Shadow DOM for isolation. The problem: static CSS is injected into document.head when the bundle loads — before any React rendering, before Shadow DOM is created. style-loader generates code that hardcodes document.head.appendChild, with no hook to intercept it.

The core difference between static CSS and Emotion:

Static CSS

Emotion

When it runs

Immediately on bundle load

At React render time

How it inserts

style-loader hardcodes document.head

JS API call, target is configurable

Interceptable

❌ No

✅ Yes, via CacheProvider

Fix: postcss-prefix-selector

Add the child app's mount point ID as a prefix to all of its static CSS selectors, so styles only apply within the child app's own DOM subtree.

npm install postcss-loader postcss-prefix-selector --save-dev

Split the webpack CSS rule into two — no prefix for node_modules, add prefix for the app's own CSS:

// Rule 1: node_modules CSS — no prefix
{
  test: /\.css$/,
  include: /node_modules/,
  use: ['style-loader', 'css-loader'],
},
// Rule 2: app CSS — add prefix
{
  test: /\.css$/,
  exclude: /node_modules/,
  use: [
    'style-loader',
    'css-loader',
    {
      loader: 'postcss-loader',
      options: {
        postcssOptions: {
          plugins: [
            ['postcss-prefix-selector', {
              prefix: '#analytics-container',
            }]
          ]
        }
      }
    }
  ]
},

Two common mistakes: the prefix must exactly match the child app's actual mount point ID, and node_modules must be excluded — otherwise third-party library styles get prefixed and break.

---

Taking Over Child App Upgrades: What I Found

v4's JSS prefix approach and its limits

When I took over the upgrade of calculator-child-app, I found that its v4 code already used createGenerateClassName to prefix JSS dynamic class names:

const generateClassName = createGenerateClassName({
  dangerouslyUseGlobalCSS: true,
  seed: 'cca',
  productionPrefix: 'cca-',
});

This adds a cca- prefix to dynamically generated class names, avoiding collisions with other apps' dynamic classes. But it doesn't touch semantic class names — .MuiButtonBase-root is hardcoded by MUI and createGenerateClassName can't affect it.

More critically: JSS injects its style tags when the child app mounts, which is triggered by route changes. By the time the child app mounts, the host app's Emotion style tags are already in <head>. JSS injects after them, with no way to control the relative position. When two engines inject different rules for the same semantic class, whichever inserts last wins — and that's JSS.

The v4 JSS prefix approach only solves dynamic class name collisions. Semantic class conflicts have no solution in v4. The only way out is upgrading to v5/v6 and switching to Emotion, where CacheProvider can control insertion position.

Two Emotion isolation strategies in v6

Looking at analytics-child-app and ai-child-app — both already upgraded to v6 — I found they used different Emotion isolation approaches.

Option 1: prepend: true (ai-child-app)

const cache = createCache({
  key: 'aca-',
  prepend: true
});

prepend: true inserts Emotion style tags at the very beginning of <head>. The child app's styles have the lowest priority and can be overridden by anything inserted after them.

Option 2: insertionPoint (analytics-child-app)

function getInsertionPoint() {
  let anchor = document.querySelector('meta[data-emotion-insertion-point="ana-"]');
  if (!anchor) {
    anchor = document.createElement('meta');
    anchor.setAttribute('data-emotion-insertion-point', 'ana-');
    const hostAnchor = document.head.querySelector('meta[data-host-css]');
    if (hostAnchor && hostAnchor.parentNode) {
      hostAnchor.parentNode.insertBefore(anchor, hostAnchor.nextSibling);
    } else {
      document.head.appendChild(anchor);
    }
  }
  return anchor;
}

const cache = createCache({
  key: 'ana-',
  insertionPoint: getInsertionPoint()
});

insertionPoint lets you specify where Emotion inserts its style tags — more precise control over insertion order compared to prepend: true.

Tradeoffs:

prepend: true

insertionPoint

Complexity

Simple

More complex, requires coordination with host app

Style priority

Lowest, easily overridden

Controllable

Use case

Child app styles can be overridden

Need precise control over insertion order

Current observation: no semantic class conflicts between same-version Emotion instances

Neither approach has produced semantic class conflicts so far. The likely reason: when both the host app and child apps are on the same MUI version, the rules each Emotion instance injects for the same semantic class are identical — so insertion order doesn't matter, and there's no conflict to observe.

This needs more validation, but so far prepend and insertionPoint show no difference in semantic class behavior when both sides are on the same MUI version.

---

The Full Picture

These problems appeared in sequence throughout the upgrade:

While upgrading the host app, the dev environment was still running v4 child app deployments. JSS and Emotion coexisted, and the dynamic style conflict surfaced. After the child apps were redeployed with v5, the dynamic conflict disappeared — but static CSS leakage appeared. App.css contained hardcoded MUI semantic classes that were polluting the host app; postcss-prefix-selector fixed it.

Taking over the child app upgrades revealed that v4 already had createGenerateClassName for JSS class name prefixing — but this only covers dynamic class names. Semantic class conflicts in v4 have no solution on the child app side. That's the root cause of the first problem. Upgrading child apps to v6 and switching to Emotion lets CacheProvider control insertion position.

These problems are specific to the v4 → v6 transition period — they arise because the host app and child apps upgrade at different times, leaving two style systems coexisting temporarily. Once the upgrade is complete, the conflicts disappear.

The static CSS leakage is a separate issue rooted in a bad practice: hardcoding MUI semantic class names directly in CSS files. If that hadn't happened, postcss-prefix-selector would never have been needed.

If you're doing a similar microfrontend MUI upgrade, the main thing to watch out for is the dynamic style conflict that comes from an unsynchronized upgrade schedule. As long as the host app and child apps are on different MUI versions, JSS and Emotion will coexist and conflict. The most direct solution is to push child app upgrades forward.

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.