Micro-Frontend Architecture: How to Split a Monolith Without Losing Your Mind
I still remember the moment I knew our frontend had become a problem.
It took 4 minutes to run our test suite. PRs sat in review for days because everyone was afraid of merge conflicts. Deploying a button color change required coordinating with three other teams. We had a 280,000-line React monolith, and it was slowly eating us alive.
That was three years ago. Since then I’ve navigated two micro-frontend migrations, made some expensive mistakes, and developed strong opinions about what actually works in production. This is that story.
What Even Is a Micro-Frontend?
The idea is simple: apply the same thinking that gave us microservices — independent, separately deployable units — to the frontend.
Instead of one giant React (or Angular, or Vue) app that every team commits to, you break the UI into smaller apps owned by individual teams. Each team ships independently. Each slice of the UI has its own repo, its own CI/CD pipeline, its own release cadence.
BEFORE (Monolith):
┌─────────────────────────────────────────────┐
│ one-giant-app │
│ Header | Dashboard | Orders | Settings │
│ (everyone touches everything) │
└─────────────────────────────────────────────┘
AFTER (Micro-Frontends):
┌──────────┐ ┌───────────┐ ┌────────┐ ┌──────────┐
│ Shell │ │ Dashboard │ │ Orders │ │ Settings │
│ (host) │ │ (MFE) │ │ (MFE) │ │ (MFE) │
└──────────┘ └───────────┘ └────────┘ └──────────┘
Team A Team B Team C Team D
That’s the pitch. Reality, as always, is more complicated.
The Three Integration Strategies (and When to Use Each)
How you stitch micro-frontends together is the most consequential architectural decision you’ll make. Get this wrong and you’ll create more problems than you solve.
Strategy 1: Build-Time Integration
Each MFE is published as an npm package. The shell app imports and bundles them together at build time.
// shell/package.json
{
"dependencies": {
"@company/dashboard-mfe": "2.4.1",
"@company/orders-mfe": "1.9.0",
"@company/settings-mfe": "3.1.2"
}
}
The catch: This isn’t really micro-frontend architecture. It’s just modular architecture with extra steps. To deploy the Orders team’s new feature, the Shell team still has to bump a package version and redeploy. You’ve added npm overhead but kept the deployment coupling.
Use it when: Teams are small (or even solo), and you want better code organization without operational complexity. Don’t call it micro-frontends.
Strategy 2: Run-Time Integration via iframes
The oldest trick in the book. Each MFE lives at its own URL and gets embedded in an iframe.
<!-- shell/index.html -->
<div id="dashboard-container">
<iframe src="https://dashboard.internal.company.com" />
</div>
The surprising truth: iframes solve almost every hard micro-frontend problem out of the box. Perfect isolation. Independent deployments. No shared global state. Different tech stacks? No problem.
The real costs: Cross-frame communication is painful (postMessage everywhere). Responsive layouts are a nightmare. Accessibility is genuinely hard to get right — focus management, screen readers, keyboard traps. And they feel clunky to users if you’re not careful.
Use it when: You need hard isolation (e.g., embedding a third-party widget), or your MFEs are truly standalone tools that don’t need to interact much.
Strategy 3: Run-Time Integration via Module Federation (The Modern Approach)
Webpack 5 (and now Vite with plugins) introduced Module Federation — the ability for one JavaScript bundle to dynamically load code from another bundle at runtime, across separate deployments.
// dashboard-mfe/webpack.config.js
new ModuleFederationPlugin({
name: 'dashboardMFE',
filename: 'remoteEntry.js',
exposes: {
'./Dashboard': './src/Dashboard',
},
shared: { react: { singleton: true }, 'react-dom': { singleton: true } }
})
// shell/webpack.config.js
new ModuleFederationPlugin({
name: 'shell',
remotes: {
dashboardMFE: 'dashboardMFE@https://dashboard.cdn.company.com/remoteEntry.js',
},
})
Now the shell can do this at runtime:
// shell/src/App.jsx
const Dashboard = React.lazy(() => import('dashboardMFE/Dashboard'));
function App() {
return (
<Suspense fallback={<Spinner />}>
<Dashboard />
</Suspense>
);
}
The Dashboard team deploys their new remoteEntry.js to the CDN. The shell picks it up on the next page load — no shell redeploy needed. That’s the magic.
The Five Problems Nobody Warns You About
Theory is easy. Here’s where things get genuinely hard.
Problem 1: Dependency Hell
Each MFE has its own node_modules. Without careful coordination, you’ll end up loading React 18.2 and React 18.3 in the same page. Or worse, two different major versions.
Module Federation’s shared config handles this, but it needs explicit care:
shared: {
react: {
singleton: true, // Only one instance allowed on the page
requiredVersion: '^18.0.0',
eager: false, // Load lazily, not in initial bundle
},
'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
}
singleton: true is non-negotiable for React. Two React instances on one page will break context, hooks, and refs in subtle, maddening ways. Add the shared config, then enforce it — a lint rule or CI check that flags any MFE shipping its own React bundle.
Problem 2: Shared State Is a Trap
The most tempting antipattern: a global Redux store or Context shared across MFEs.
// ❌ Don't do this
// shell/src/globalStore.js
export const store = createStore(rootReducer);
// orders-mfe/src/OrderList.jsx
import { store } from 'shell/globalStore'; // tight coupling disguised as convenience
You’ve just recreated the monolith in a trenchcoat. Now the Orders MFE can’t deploy without the shell, because it’s importing from it.
What to do instead: Keep each MFE’s state local. Share the minimum necessary via well-defined contracts: URL parameters, custom events, or a thin event bus.
// Lightweight event bus for cross-MFE communication
// shell/src/eventBus.js
const bus = new EventTarget();
export const emit = (event, detail) => bus.dispatchEvent(new CustomEvent(event, { detail }));
export const on = (event, cb) => bus.addEventListener(event, cb);
export const off = (event, cb) => bus.removeEventListener(event, cb);
// orders-mfe: emit an event when an order is placed
emit('order:placed', { orderId: '12345', total: 49.99 });
// notifications-mfe: listen for it
on('order:placed', ({ detail }) => showToast(`Order ${detail.orderId} confirmed!`));
Clean, decoupled, and each MFE can be deployed in isolation.
Problem 3: Design System Drift
Without discipline, each MFE will slowly develop its own button component, its own color tokens, its own spacing system. Six months in, your app looks like it was designed by five people who never spoke to each other — because it was.
The fix: A shared design system as a separate, versioned package. But version it carefully.
@company/[email protected] — locked via shared config in Module Federation
The design system is the one dependency that should be shared. Everything else, keep isolated.
Problem 4: Performance — You’re Loading More JavaScript
A micro-frontend architecture almost always means more JavaScript on the page. Multiple remoteEntry.js files, multiple framework instances if you’re not careful, multiple routers.
Track your bundle metrics religiously:
// Add to your CI pipeline — fail if initial JS exceeds budget
// webpack.config.js
performance: {
maxEntrypointSize: 170000, // 170KB gzipped
maxAssetSize: 250000,
hints: 'error', // Fail the build, don't just warn
}
And lean on lazy loading aggressively. Users shouldn’t pay the cost of loading the Settings MFE when they’re on the Dashboard.
Problem 5: Testing Gets Complicated
Unit tests per MFE are easy — same as before. But integration testing across MFE boundaries is where teams struggle.
My recommendation: contract testing. Each MFE publishes a contract describing its interface (the events it emits, the props it accepts). The shell validates against those contracts in CI, without needing to spin up every MFE.
Tools like Pact handle this well, or you can roll a simple JSON schema validation in your CI pipeline.
The Architecture I’d Recommend Today
For a mid-size product team (3–6 frontend teams), here’s my pragmatic setup:
┌─────────────────────────────────────────────────────────┐
│ Shell App (Host) │
│ - Routing │
│ - Auth / session │
│ - Design system tokens │
│ - Event bus │
└──────┬──────────────┬──────────────┬────────────────────┘
│ │ │
Module Fed Module Fed Module Fed
│ │ │
┌──────▼──────┐ ┌─────▼──────┐ ┌────▼──────────┐
│ Dashboard │ │ Orders │ │ Settings │
│ MFE │ │ MFE │ │ MFE │
│ (Team B) │ │ (Team C) │ │ (Team D) │
└─────────────┘ └────────────┘ └───────────────┘
Shell responsibilities: routing, authentication, session, shared design system, event bus. Nothing else.
MFE responsibilities: everything inside their domain boundary. Own their data fetching, own their state, own their tests.
The rule I enforce: No MFE imports from another MFE. Communication only through the event bus or URL. If two MFEs need to share logic, that logic belongs in the design system or a shared utility package — not in either MFE.
Is Micro-Frontend Right for Your Team?
Micro-frontends introduce real operational overhead. Be honest about whether you need them:
| Signal | Recommendation |
|---|---|
| < 3 frontend engineers | Monolith. Micro-frontends will slow you down. |
| 3–8 engineers, one codebase | Modular monolith with clear domain folders |
| Multiple teams, frequent merge conflicts | Strong candidate for MFEs |
| Teams need independent deploy cadences | MFEs are worth the investment |
| Different tech stacks per team | MFEs (iframes or Module Federation) |
The honest truth: most teams that migrate to micro-frontends are solving a people and process problem with a technology solution. If your teams can agree on shared standards and communicate well, a well-structured monolith might serve you better for longer than you think.
But when you genuinely need independent deployability and team autonomy at scale? Module Federation is mature enough, the tooling has caught up, and the patterns are now well-understood.
What I’d Do Differently
Looking back at those two migrations:
I’d define the event bus contract first, before writing a single component. The communication layer between MFEs is your most critical API. Treat it like one.
I’d version the design system from day one, not after three teams have forked the button component.
I’d set bundle size budgets in CI on day one and make them fail the build. “We’ll optimize later” is a lie we all tell ourselves.
And honestly? I’d question whether we needed it at all — at least one of those migrations happened because it was architecturally fashionable, not because the team had actually outgrown the monolith. The best architecture is the simplest one that solves your actual problem.
Wrapping Up
Micro-frontend architecture is powerful when applied to the right problems: large teams, independent deployments, domain ownership at scale. Module Federation has made the integration story dramatically better than it was even two years ago.
But it’s not free. Shared dependencies, state isolation, design consistency, and integration testing all require intentional effort that a monolith handles for you by default.
My three-sentence summary:
Use Module Federation for run-time integration. Enforce singleton shared dependencies. Never let MFEs import from each other — the event bus is your friend.
If you’re in the middle of a micro-frontend migration — or trying to decide whether to start one — drop a comment. I’ve been in the trenches on this and I’m happy to dig into specifics.
I write about frontend architecture, performance, and the messy realities of building large-scale UIs. Follow me on DEV if that’s your kind of thing.
