Micro-frontends at Scale: Lessons Learned from Migrating a Monolith

How our engineering team split a legacy React monolith into independent, deployable micro-frontends without interrupting user experiences.

As engineering teams grow, the limits of a monolithic frontend architecture quickly become apparent. Merge conflicts, long build times, and coordinated deployments create organizational friction. At StartupWire, we recently completed a 12-month migration from a large React monolith to a federated micro-frontend architecture. Here is what we learned along the way.

#

Why We Decided to Migrate

Our main application was maintained by four separate product squads. A single line change by the Checkout team could block the Catalog team from releasing. Build pipelines took over 20 minutes, and rollbacks meant reverting everyone's changes, not just the buggy feature.

We set three primary goals: 1. Independent Deployability: Each team should be able to deploy their domain-specific UI without coordinating with others. 2. Incremental Migration: The monolith had to remain functional during the transition. 3. Consistent User Experience: The final application must look like a single unified app, not a collection of disjointed pages.

#

Architectural Decisions: Module Federation

We evaluated several approaches (iframes, build-time integration via npm packages, run-time integration). Ultimately, we chose Webpack Module Federation (and subsequently Vite's equivalent using native ES modules) for runtime integration. This allowed us to load remote JavaScript bundles dynamically.

``` [ App Shell (Host) ] / | [ Auth Remote ] [ Shop Remote ] [ Blog Remote ] ```

#

Critical Lessons Learned

##

1. Establish a Shared Design System First

Without a shared library of UI tokens and basic components, teams will write duplicate styles, leading to visual inconsistencies. We created a core library packaged as a lightweight, versioned design system dependency.

##

2. Handle Shared State with Care

Avoid global state managers like Redux spanning across micro-frontends. Instead, use custom events, query parameters, or lightweight service buses to pass minimal data. Micro-frontends should be decoupled and share as little state as possible.

##

3. Optimize for Web Performance

Loading multiple independent applications can impact page load times. Implement aggressive code splitting, share core dependencies (like React and React-DOM) as singletons via Module Federation configuration, and utilize modern prefetching techniques.