How to configure Module Federation in React Router with Vite?

[neetigyachahar]

I am typically trying to set up a React Router (framework mode) project with Module Federation enabled.

You can explore a demo repo here: https://github.com/neetigyachahar/react-router-vite-module-federation

There are two apps, host and remote-1 in it. First, I'm trying to configure remote-1 app work properly.

Here is a snippet of my vite.config.ts file in the remote-1 app.

import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
import { federation } from "@module-federation/vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
    reactRouter(),
    tsconfigPaths(),
    federation({
      name: "remote-app",
      filename: "remoteEntry.js",
      exposes: {
        "./Button": "./app/components/Button",
      },
      shared: {
        react: {
          singleton: true,
          requiredVersion: "^19.0.0",
        },
        "react-dom": {
          singleton: true,
          requiredVersion: "^19.0.0",
        },
      },
    }),
  ],
  server: {
    port: 5001,
  },
  build: {
    target: "esnext",
  },
});

The build is successfully created but if I run it, I get the following error:

chahar@Neetigyas-Laptop remote-1 % npm start
> start
> react-router-serve ./build/server/index.js

file:///Users/chahar/projects/demo/rr-vite-mf/remote-1/build/server/assets/index.cjs-qyK6uRiB.js:1
import require$$0 from '@module-federation/runtime-core';
       ^^^^^^^^^^
SyntaxError: The requested module '@module-federation/runtime-core' does not provide an export named 'default'
    at ModuleJob._instantiate (node:internal/modules/esm/module_job:181:21)
    at ModuleJob.run (node:internal/modules/esm/module_job:264:5)
    at onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:583:26)
    at run (/Users/chahar/projects/demo/rr-vite-mf/remote-1/node_modules/@react-router/serve/dist/cli.js:80:15)

Also, for the host app, I am getting the error as mentioned in this repo: https://github.com/Hunga1/module-federation-react-router-framework-reprex/tree/main

[vite] (ssr) Error when evaluating SSR module virtual:react-router/server-build: require is not defined
      at eval (/Users/myuser/module-federation-react-router-framework-reprex/react-router-framework-host/node_modules/__mf__virtual/host__loadShare__react_mf_2_router__loadShare__.js:8:25)
[vite] Internal server error: require is not defined
      at eval (/Users/myuser/module-federation-react-router-framework-reprex/react-router-framework-host/node_modules/__mf__virtual/host__loadShare__react_mf_2_router__loadShare__.js:8:25)

What could be the possible fixes for these?

[ajmeraaxesh]

any updates on this?

[DallasCarraher]

@neetigyachahar

Solution: Runtime-Only Module Federation

Both errors you're encountering stem from the same root cause:

1. require is not defined - The @module-federation/vite plugin transforms shared dependency imports (react, react-dom, react-router) to route through CJS virtual modules. This breaks Vite's ESM-based SSR evaluation.

2. does not provide an export named 'default' - Similar ESM/CJS interop issue during SSR where the runtime-core module isn't being imported correctly.

The @module-federation/vite plugin is designed primarily for CSR (client-side rendering) apps and has known compatibility issues with SSR frameworks like React Router in framework mode.

The Fix: Use @module-federation/runtime Directly

Remove the federation plugin entirely and use @module-federation/runtime directly on the client side. This bypasses SSR completely since MF is only initialized and used in browser code.

Result:

SSR (Server)

React renders normally
No MF plugin interference
Remote component returns
placeholder/fallback

Client (Browser)

MF runtime initializes
Remotes registered
loadRemote() fetches remote
Component renders

---

How to implement

1. Remove Federation Plugin from Vite Config

vite.config.ts - Remove the federation() plugin call entirely:

import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
// REMOVE: import { federation } from "@module-federation/vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
    reactRouter(),
    tsconfigPaths(),
    // REMOVE the entire federation({ ... }) call
  ],
  server: {
    port: 5000,
  },
  build: {
    target: "esnext",
  },
});

2. Add Runtime Dependency

npm install @module-federation/runtime

3. Initialize MF Runtime in Client Entry

Create or update app/entry.client.tsx:

import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import { init } from "@module-federation/runtime";

// Initialize Module Federation runtime BEFORE hydration
init({
  name: "host",
  remotes: [
    {
      name: "remote1",
      alias: "remote1",
      entry: "http://localhost:5001/assets/remoteEntry.js",
    },
  ],
  shared: {
    react: {
      lib: () => import("react"),
      singleton: true,
      requiredVersion: "^19.0.0",
    },
    "react-dom": {
      lib: () => import("react-dom"),
      singleton: true,
      requiredVersion: "^19.0.0",
    },
  },
});

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  );
});

4. Create a Client-Only Wrapper for Remote Components

app/components/RemoteButton.tsx:

import { loadRemote } from "@module-federation/runtime";
import { lazy, Suspense, useEffect, useState, type ComponentType } from "react";

interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
}

// Lazy load using runtime API
const RemoteButtonComponent = lazy(async () => {
  const module = await loadRemote<{ default: ComponentType<ButtonProps> }>(
    "remote1/Button"
  );
  if (!module) {
    throw new Error("Failed to load remote Button component");
  }
  return { default: module.default };
});

export function RemoteButton(props: ButtonProps) {
  const [isMounted, setIsMounted] = useState(false);

  useEffect(() => {
    setIsMounted(true);
  }, []);

  // SSR: render a placeholder
  if (!isMounted) {
    return <button disabled style={{ opacity: 0.5 }}>{props.children}</button>;
  }

  // Client: render the actual remote component
  return (
    <Suspense fallback={<button disabled>Loading...</button>}>
      <RemoteButtonComponent {...props} />
    </Suspense>
  );
}

5. For the Remote App

For the remote, use a separate Vite config for building federated modules only (no SSR):

remote-1/vite.federation.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { federation } from "@module-federation/vite";

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: "remote1",
      filename: "remoteEntry.js",
      exposes: {
        "./Button": "./app/components/Button",
      },
      shared: {
        react: { singleton: true, requiredVersion: "^19.0.0" },
        "react-dom": { singleton: true, requiredVersion: "^19.0.0" },
      },
    }),
  ],
  build: {
    target: "esnext",
    outDir: "dist-federation",
  },
});

Build with: vite build --config vite.federation.config.ts

---

Why This Works

With Plugin (Broken)	Runtime-Only (Working)
Plugin hijacks all shared imports	No build-time transformation
Creates CJS virtual modules	Pure ESM throughout
Breaks Vite SSR evaluation	SSR works normally
require is not defined errors	No SSR interference

---

Trade-offs

• ⚠️ Remote components won't be SSR'd (they render a placeholder during SSR)
• ⚠️ Slightly slower first load (manifest fetched at runtime)
• ⚠️ Remote URL configuration moves from build-time to runtime

---

Summary

The @module-federation/vite plugin has fundamental incompatibilities with SSR frameworks. The runtime-only approach sidesteps these issues by:

1. Not using the Vite plugin at all
2. Initializing MF only in client code (entry.client.tsx)
3. Using loadRemote() with proper client-side guards
4. Rendering fallbacks during SSR

This is currently the most reliable way to use Module Federation with React Router in framework mode until the MF Vite plugin gains proper SSR support.

[jgodi]

When you do it this way, then HMR for the remotes/host is broken. Any suggestions there?