I Migrated a Monolith to Microfrontends. The Real Question Was Never “How.

When microfrontends actually make sense, when they don’t, and the calls I would make again.

For a while now I have been leading the frontend for a sanctions-screening platform at a large logistics company. It screens shipments at scale, along with the parties, vessels, and people attached to them. On this kind of platform, a broken screen is not just a bug, it is a compliance problem.

When I joined, it was a monolith. Shipment, party, and vessel screening all lived in one application. And for a long time, that was fine. A monolith is not a sin. Most teams should start there.

So this is not me telling you to split your app into ten pieces. It is the opposite. Here is how we actually decided to migrate, and the questions I wish more people asked before chasing the microfrontend hype.

The pain that started the conversation

Nobody migrates because the architecture diagram looks cool. We did it because shipping had become painful.

Releases happened per module, but the code did not cooperate. We wanted to ship shipment screening without touching vessel screening, but everything lived in one codebase. So every release meant maintaining multiple release branches and cherry-picking changes out of other modules by hand. Build times kept climbing. Keeping release branches in sync with main was a constant headache. And the worst part: a fix in party screening redeployed vessel and shipment screening too, even though nothing in them had changed. Pushing untouched, production-critical code through deploy for no reason is exactly the risk you do not want on a compliance platform.

At some point these stopped being annoyances and became a tax on every release. That is the real signal. Not the hype. The friction.

Do you actually need this?

Before writing any shell or remote code, I made us answer one thing honestly: does this platform genuinely need to be a microfrontend, or do I just want it to be?

Microfrontends are not free. More boundaries, more coordination, more ways to break in the seams. If your app has no natural reason to split, you get all the cost and little of the benefit.

The test I used: does your product divide cleanly along the same lines your teams and ownership do? For us, yes. Shipment, party, and vessel screening were genuinely separate product areas with separate workflows, stakeholders, and ownership. The monolith was the only thing pretending they were one blob.

That alignment is the whole game. A tightly woven flow where everything depends on everything will fight you. Several distinct surfaces under one roof will finally let your architecture match reality. If you have the second, go. If you have the first, save yourself the trouble.

Monorepo or polyrepo

For most teams, monorepo is the right default: simpler pipelines, shared tooling, consistent versions. If you are unsure, start there.

We went polyrepo, deliberately, for two reasons and only one was technical. First, organizational: these were different projects with different ownership, and polyrepo made those boundaries real instead of a convention. Second, the one that sealed it: auditing. A repository per app gave us cleaner audit trails and clearer ownership of changes, which compliance needed.

But I want to be honest about the cost, because nobody warns you about this one. Every remote, and the shell, depends on a shared common module: our UI kit, shared utilities, and types. In the monolith, that code was always in sync by definition, because it lived right there in the same app. In polyrepo it becomes its own repository, and now you have to keep every single remote on the right version of it. That sync work never stops. It is a real, ongoing tax, and you should budget for it from day one rather than discovering it after your third “why is this remote on the old design system” bug.

So we traded developer-experience overhead, including that shared-module sync, for boundaries that satisfied compliance. I would make that trade again. But without audit or organizational pressure, keep the simplicity of a monorepo.

The part nobody warns you about: routing

We used Vite with Module Federation, and routing was the rough part. Once a shell orchestrates multiple remotes, who owns which route stops being obvious. Does the shell own top-level routes and hand off? Do remotes own their internal routes? What about a remote navigating to a route inside another remote? Getting this right took real iteration, and it never shows up in “hello world” demos.

One practical rule: decide your routing-ownership model early, write it down, keep it boring and consistent. Teams rarely struggle with the build. They struggle with the seams, and routing is the biggest one.

How I would decide again

1. Start with the pain, not the pattern. No friction, no microfrontend problem yet.
2. Check that your product divides the way your teams do.
3. Default to monorepo. Choose polyrepo only for a real reason.
4. Respect the cost, including keeping the shared module in sync across remotes.
5. Solve your routing and seams first.

Microfrontends are a tool, not a destination. We reached for them because our monolith had outgrown itself and our product was already divided in a way the architecture refused to acknowledge. That is the right reason. The hype is not.

If you are staring at a monolith wondering whether to jump, do not ask how to migrate. Ask whether you should. Most of the value is in answering that honestly.

If you have done a migration like this, I would like to hear how you handled the monorepo versus polyrepo call.