Navigating Home: A Conflict Resolution Guide in React Router and Module Federation

Micro Frontends (MFEs) offer a powerful architectural approach, allowing large-scale front-end monoliths to be decomposed into smaller, independently developed, tested, and deployed applications. Webpack 5’s Module Federation acts as the essential runtime coordinator, enabling these disparate applications—or “remotes”—to share code and dependencies with the central “host” application. While this setup grants enormous flexibility, it introduces significant complexity in managing shared state and routing, particularly when using a powerful state-aware library like React Router V6 (RRV6).

The core challenge lies in history management. React Router relies on a single, global router context to manage the browser’s URL and history stack. In a federated environment, if both the host and a remote micro frontend attempt to render their own top-level router components (such as or ), a fundamental conflict arises. This almost immediately triggers runtime errors stating that a router cannot be rendered inside another router, leading to unstable navigation, history stack corruption, or application crashes. Resolving this requires a two-pronged strategy: first, establishing a single, shared instance of the routing library; and second, implementing a history synchronization mechanism across applications with isolated internal routing contexts.

This comprehensive guide details the precise, verified techniques—from foundational Webpack configurations to advanced event-based history synchronization—required to successfully implement conflict-free routing with React Router V6 in a Module Federation architecture. The goal is to make the entire application feel like one seamless product, masking the underlying complexity of its distributed nature.

Understanding the Core Conflict: Nested Routers and Concurrent Rendering

The error message “Uncaught Error: You cannot render a inside another . You should never have more than one in your app” is the primary symptom of this architectural clash. This is not merely a styling issue but a direct violation of React Router’s design principles. RRV6 components like and navigation hooks like useNavigate depend on context provided by a single root router instance, typically provided by or in the host application.

When a host application dynamically loads a micro frontend using Module Federation and React’s lazy loading mechanism, the MFE component itself may inadvertently wrap its content in a new, internal router context (for example, if the MFE was designed to run standalone). When the host’s primary router is still mounted, and the remote MFE is also attempting to mount its router within the same component tree, the conflict occurs. This problem has been observed to become particularly acute in modern React versions (such as React 19) due to overlapping concurrent render phases during rapid page transitions. If the previously active MFE has not fully unmounted its router context before the new MFE attempts to load its own, the system registers two concurrent, top-level router instances.

The Two Levels of Routing Management

In a micro frontend architecture, routing must be segmented into two distinct concerns:

1. External/Global Routing (The Host’s Responsibility): This involves managing the browser’s physical URL, handling navigation between different micro frontends, and defining the top-level path structure (e.g., /dashboard, /profile, /settings). The host application—often referred to as the Shell App—must be the sole owner of the browser’s history object.
2. Internal/Scoped Routing (The Remote’s Responsibility): This involves managing the specific views and state within a single micro frontend, independent of the main browser URL changes. For instance, within the /dashboard MFE, navigation might occur between /dashboard/home and /dashboard/reports. The MFE handles this internal state change without forcing a full page reload or disrupting the host’s history.

The most robust solution ensures that the remote MFE only uses a router that does not touch the browser’s history object, effectively isolating the application’s internal routes.

Foundational Solution 1: Dependency Singletonization

The very first and most critical step in implementing stable RRV6 routing across federated applications is ensuring that all involved applications—the host and all remotes—are using a single, shared instance of the react-router-dom package at runtime. If the host loads version 6.23 and the remote loads 6.20, both applications will operate on different internal contexts and state management logic, leading directly to unpredictable behavior and conflicts.

The Webpack Module Federation Configuration

Module Federation allows developers to explicitly define shared dependencies that should be loaded only once, with the highest available semantic version being utilized across the entire application stack. This is achieved by configuring the ModuleFederationPlugin in the webpack.config.js file for both the host and the remote applications. For libraries that maintain a global internal state, such as React, React DOM, and React Router, this configuration is mandatory.

Implementing singleton: true for react-router-dom

The shared configuration block must explicitly list react-router-dom and enable the singleton option. The singleton hint tells Webpack to allow only one version of this shared module within the shared scope. If different versions exist, the highest semantic version is used, and it is loaded only once at application startup. This prevents the runtime from being poisoned by conflicting internal states from multiple router libraries.

The configuration snippet for both the Host and the Remote applications would resemble the following structure:

• Core Shared Dependencies:Dependencies like react, react-dom, and react-router-dom must be listed. For these state-critical libraries, singleton: true is non-negotiable to maintain a consistent execution environment. If not set, different versions of the same dependency across the host and remote will result in each loading their own copies, causing the very conflicts we are trying to resolve.
• Required Version Pinning:It is best practice to also specify a requiredVersion (using the package.json version) to ensure compatibility. While singleton: true prioritizes the highest version, defining a minimum required version acts as a safety measure.
• Avoiding Duplication:The goal is to reduce duplication of common libraries. Module Federation’s dependency sharing mechanism ensures that the remote MFE will not download its own copy of the router if the host has already loaded a compatible singleton version, significantly improving performance and preventing environment conflicts.
• Configuration Location:This sharing configuration must be present in the webpack.config.js of every application—the host and all remotes—that uses the React Router V6 library.

By enforcing this singleton pattern, the application guarantees that all components, regardless of which micro frontend they belong to, interact with the same history management utility provided by the single, shared React Router V6 instance, eliminating the root cause of the nested router conflict.

Foundational Solution 2: Architecture of Isolation

While singletonization solves the dependency conflict, it does not solve the architectural problem of history management. Even with a shared library, if the remote MFE tries to use it will attempt to manipulate the browser’s URL, leading to collisions with the host’s own history logic. The solution is to ensure that the host app owns all top-level URL control, while the remote MFEs use a separate, isolated routing context for their internal navigation.

Centralized Routing Ownership in the Host Shell

The Host or Shell application must be configured to:

1. Define the Global Router: Use the appropriate browser router for the top level, typically or (or createBrowserRouter in V6.4+).
2. Define Top-Level Routes: All primary, root-level paths (e.g., /dashboard, /profile) are defined here. The element for these routes is typically the lazily-loaded MFE component.
3. Control Browser History: The host is the only component allowed to use the standard browser history API (window.history.pushState).

This centralized ownership ensures that the host maintains a coherent, single source of truth for the application’s URL state, allowing for reliable back/forward button functionality and deep linking. When the host matches a route to a remote MFE, it renders the MFE component, which is then responsible for its internal routing.

Scoped Internal Routing using MemoryRouter

For internal navigation within a remote micro frontend, the use of is the best practice for isolation. manages history entirely in memory, without reading from or writing to the browser’s address bar. This effectively creates an isolated, sandboxed routing environment for the remote MFE.

• Isolation:By using MemoryRouter, the remote MFE can define its own internal routes (e.g., /, /reports) without conflicting with the host’s URL path (which might be /dashboard). The MFE’s navigation actions (like calling useNavigate(‘/reports’)) only update its in-memory history stack, preserving the host’s top-level URL.

• Path Context:When the host renders the MFE at a specific base path (e.g., the /dashboard route), the MFE should be configured to run its internal routes relative to that base path. While React Router V6 handles nested routing automatically, the MFE’s internal routes should be defined using relative paths within its block to ensure they are correctly scoped under the host’s path segment. For instance, if the MFE is loaded at /dashboard/*, its internal route definitions should match the segment after /dashboard/.
• Internal Routing Mechanism:The MFE’s entry point, which is exposed via Module Federation, will wrap its internal application logic in and its own block. This provides a full routing capability—using useParams, useNavigate, and useLocation—within the MFE without interfering with the host.

This architectural separation is the core strategy for avoiding nested router conflicts: the host uses the browser router, and the remote uses the in-memory router. The final challenge is then synchronizing the state between these two isolated contexts.

Implementing Cross-Micro Frontend Navigation Synchronization

The architecture of isolation creates a new challenge: if a user clicks a link inside the “Dashboard” MFE that should navigate to a different MFE, such as the “Profile” MFE (e.g., navigating from /dashboard/reports to /profile/settings), the cannot directly trigger the browser’s URL change. Furthermore, if the user manually updates the browser URL, the MFE’s internal state needs to be updated. This synchronization requires a loosely coupled, event-based communication utility.

Event-Based Communication Mechanism (Custom Events)

The recommended mechanism for communication across completely independent Module Federation boundaries is the use of Custom Events dispatched via the global window object. This pattern, often referred to as an Event Bus, allows the host and remotes to communicate without having direct knowledge of each other’s internal structure, maintaining the architectural decoupling necessary for independent deployment.

The communication must flow in both directions:

1. Remote to Host (Cross-MFE Navigation): When a remote MFE needs to trigger a navigation that switches to a different MFE, it dispatches a custom event. The host listens for this event and executes the top-level navigation, thereby updating the browser’s history.
2. Host to Remote (URL Update/Base Path Synchronization): When the host loads a remote MFE, or when the user manually changes the URL, the host needs to inform the MFE what its current base path is so the MFE can set the initial history state of its internal MemoryRouter.

Synchronizing Browser History and Internal Routers

The implementation involves a custom utility, which can be an exported function or hook, that leverages the window.dispatchEvent and window.addEventListener APIs.

1. The Synchronization Utility

A simple synchronization utility allows the remote to communicate its navigation intent to the host:

• In the Remote MFE (Dispatch):When an MFE wants to navigate externally (e.g., from /dashboard/home to /profile), it calls an exposed utility that dispatches a custom event, such as mfe:navigate, carrying the target path in its detail property. This event does not affect the browser URL yet; it only signals the intent to the host.
• In the Host App (Listen and Handle):The host application, which contains the main , registers a listener on the window object for the mfe:navigate event. Upon receiving the event, the host calls its global navigation function (obtained from the shared RRV6 instance) or uses window.history.pushState to perform the actual URL update. Because the host is the sole owner of the , this action is safe and non-conflicting.

2. Initializing MemoryRouter State

When a remote MFE loads, its internal MemoryRouter needs to know the specific path it should display. This path is derived from the host’s current URL, relative to the MFE’s base path.

• Host Calculation:If the browser URL is /dashboard/reports/id-123 and the host loads the “Dashboard” MFE at the /dashboard base route, the host extracts the remaining path segment: /reports/id-123. This relative path is then passed as a prop to the lazy-loaded MFE component.
• Remote Initialization:The remote MFE component receives this relative path and uses it to initialize the MemoryRouter via the initialEntries prop. This sets the MFE’s internal history stack to the correct location, ensuring that the MFE renders the corresponding internal route (e.g., the /reports/:id view) without having to read the conflicting browser URL itself.

This dual-strategy—singletonization for dependencies and synchronized, isolated routing for history—establishes a stable and scalable micro frontend routing framework using React Router V6.

Advanced Routing Strategies for Dynamic Discovery

The monolithic approach to routing requires defining the entire route tree statically at application startup. In a highly distributed Module Federation environment, this is often impossible, as remotes may expose their routes asynchronously and on-demand. React Router V6 offers an advanced pattern, often called the “Fog of War” approach, that allows the host to discover and inject remote routes at runtime, solving the problem of the full route tree.

The Challenge of the Full Route Tree

When using createBrowserRouter in the host application, the standard practice is to pass a full array of route definitions. In MFEs, however, the route definition for a remote MFE (e.g., all sub-routes under /profile/*) is contained within the remote application’s bundle, which is only downloaded and evaluated when the user navigates to that path. Until then, the host is unaware of the remote’s specific routes, leading to potential “404 Not Found” errors if the host attempts to match a path that belongs to a non-yet-loaded remote.

Traditional lazy loading with React.lazy() addresses component loading, but it doesn’t solve the core RRV6 data API challenge: the router needs to match the URL to a route definition before rendering and data fetching occurs. If the route definition is missing, the process fails.

Leveraging patchRoutesOnNavigation (Fog of War)

React Router V6.4+ (and its subsequent versions) introduced the patchRoutesOnNavigation option within createBrowserRouter (or similar APIs like unstable_patchRoutesOnMiss), which is specifically designed for complex, asynchronous routing scenarios, including Module Federation.

This feature allows the host router to dynamically patch new route definitions into the existing route tree during the navigation process. The mechanism works as follows:

• Initial Setup:The host’s createBrowserRouter is initialized with a minimal route tree—perhaps just the index route and top-level placeholders (e.g., path: “/blog/*”) that represent the remote MFEs. The core logic is defined in the patchRoutesOnNavigation function.
• Dynamic Discovery:When a navigation attempt occurs (e.g., the user enters /blog/first-post), the patchRoutesOnNavigation function is executed. This function receives the target path and can inspect it.

  If the path matches a known remote MFE (e.g., if it starts with /blog), the host can trigger the Module Federation loading process for the “Blog” remote. The remote application is configured to expose its route definitions (or a function that returns them) via its remoteEntry.js.

• Route Patching:Once the remote route definitions are asynchronously loaded, the patch function provided by the API is called. This function injects the new routes into the existing router structure. For example, the host might patch the newly loaded Blog routes as children of the existing /blog placeholder route.

  This technique allows the router to dynamically “discover” the routes it needs, expanding the map of available paths only as required by the current navigation, hence the term “Fog of War” (where the map expands only as the player explores it).

• Benefits:This advanced method allows the host to use all the benefits of the RRV6 Data APIs—such as loaders and actions—even for lazily-loaded MFE routes, ensuring optimal parallel data fetching and performance. This is generally preferred over manually managing the MFE’s internal history with a if the remote MFE needs to utilize RRV6’s powerful data management capabilities.

Implementing this requires that the remote MFE is designed to export not just a component, but an array of route objects that the host can consume and patch into its root router instance.

Optimizing Performance and Developer Experience

Successful implementation of React Router V6 in a Module Federation environment extends beyond merely resolving the nested router conflict; it requires careful consideration of performance and consistency across the entire distributed application.

Performance Considerations (Lazy Loading and Data Fetching)

The interplay between Module Federation’s dynamic import capabilities and React’s lazy loading mechanisms can introduce performance pitfalls if not managed correctly, particularly concerning data fetching.

One common anti-pattern in single-page applications (SPAs) is serial fetching: a component is lazy-loaded (waiting for the JavaScript bundle), and only once it mounts does it trigger a data fetch (waiting for the API response). This serial process doubles the perceived latency for the user.

• Leveraging V6 Loaders:The preferred solution is to integrate data fetching with the routing itself using RRV6’s loader functions. The host router (when using the patchRoutesOnNavigation strategy) can be configured to execute the remote MFE’s loaders before the component is rendered. This allows the host to fetch both the remote MFE’s code bundle and its required data concurrently. This parallel fetching significantly improves user experience by presenting the fully loaded page much faster.
• Module Federation Prefetching:Module Federation offers performance optimization features like Data Prefetching, which can be applied to remote modules. While RRV6 loaders are route-bound, Module Federation prefetching allows the developer to specify remote modules (or exposed components) that should be downloaded in the background when the user is likely to need them, further reducing navigation latency to a “secondary screen” or MFE.

Handling Protected Routes and Shared Context

Authentication and authorization are critical services that must be shared consistently across all micro frontends. Since Module Federation already ensures a single shared instance of core dependencies, sharing authentication context follows a similar pattern.

[article9]

The ideal strategy for protected routes involves the following steps:

1. Shared Authentication Library: The authentication mechanism (e.g., a custom hook, a state management library like Redux or Zustand, or a simple context provider) should be exposed via the Module Federation shared configuration, ensuring every MFE uses the same authentication logic and global state.
2. Host-Level Gatekeeping: For routes that load an MFE component, the host can implement the protection logic. In RRV6, this is achieved by defining a custom component in the element prop of the that checks the authentication status (from the shared context). If the user is not authenticated, this component can return a element redirecting to the login page. This is the official and simplest way to implement protected routes in V6.
3. Role-Based Authorization (Remote Check): For authorization logic (checking if an authenticated user has the correct role to view internal MFE sub-routes), the MFE itself performs the check using the shared authentication data, potentially wrapping its internal with a custom component that navigates the user to an unauthorized page if roles do not match.

This separation ensures that the host handles the initial access check to the MFE container, while the MFE handles the fine-grained permission checks for its internal views, relying on a universally shared and synchronized context.

Other vital considerations for a good developer experience (DX) and reliable application stability include:

[article10]

• Avoiding Global CSS Collisions:Micro frontends must prevent styling from one MFE from leaking into another, which would be a severe visual conflict. Strategies for isolation include using CSS Modules, utility frameworks like Tailwind (with namespace prefixes), or adopting scoped solutions like CSS-in-JS.
• Standardized Design Systems:The visual coherence of the application relies on a shared set of components. The entire design system should be published as an independent NPM package and then consumed by the host and all remotes via the Module Federation shared configuration. This ensures that all components—buttons, navigation bars, typography—render identically across the application, regardless of which MFE is displaying them.
• Consistent Error Boundaries:The host should wrap the lazy-loaded remote components in boundaries to handle the loading state (e.g., showing a spinner) while the remote component is downloaded. Crucially, the host should also incorporate Error Boundaries around the remote component to gracefully handle runtime failures within the MFE without crashing the entire shell application, maintaining resilience.

By diligently applying these advanced architectural and performance best practices, the distributed nature of Module Federation can be leveraged for faster development and deployment without compromising the seamless, high-performance experience expected of a single-page application built with React Router V6.

Conclusion

The integration of React Router V6 within a Module Federation micro frontend architecture presents a solvable challenge, provided the fundamental conflict—the presence of multiple, history-aware router contexts—is addressed through a systematic, multi-layered strategy. The foundation of this solution rests on Webpack Module Federation’s dependency singletonization, specifically setting react-router-dom to singleton: true in the shared configuration to ensure a single, consistent library instance runs at runtime. Architecturally, the conflict is resolved by establishing a clear separation of concerns: the Host application maintains sole ownership of the global browser history using or , while each Remote MFE utilizes an isolated for its internal, scoped navigation.

Finally, event-based communication via the global window object (custom events) is essential for synchronizing the two history contexts, allowing seamless cross-MFE navigation without coupling the applications. For complex, large-scale applications, the advanced patchRoutesOnNavigation (“Fog of War”) pattern offers a powerful way to leverage the full capabilities of the V6 Data APIs by dynamically loading and injecting remote route definitions into the host router, achieving both performance and decoupling. Adhering to these established patterns—from foundational configuration to advanced runtime synchronization—is crucial for building scalable, high-performance, and resilient micro frontend applications with React Router V6.