NextFederationPlugin vs ModuleFederationPlugin: Complete Guide

// apps/Content/next.config.js — Next.js Remote (Production)
const { NextFederationPlugin } = require("@module-federation/nextjs-mf");

/** @type {import('next').NextConfig} */
const nextConfig = {
  // basePath and assetPrefix route all assets under /content/
  // so Nginx can proxy requests to this remote's container
  basePath: "/content",
  assetPrefix: "/content",

  // standalone output for Docker deployment
  output: "standalone",

  reactStrictMode: true,

  transpilePackages: ["@myapp/store", "@myapp/api", "@myapp/seo"],

  images: {
    remotePatterns: [
      { protocol: "https", hostname: "cdn.myapp.com" },
      { protocol: "https", hostname: "ik.imagekit.io" },
    ],
  },

  webpack(config, { isServer }) {
    config.plugins.push(
      new NextFederationPlugin({
        name: "Content",
        // Next.js convention — remoteEntry lives inside _next/static/chunks/
        filename: "static/chunks/remoteEntry.js",
        exposes: {
          "./FAQ": "./components/FAQ",
          "./TermsAndConditions": "./components/TermsAndConditions",
          "./PrivacyPolicy": "./components/PrivacyPolicy",
          "./SizeGuide": "./components/SizeGuide/SizeGuide",
        },
        shared: {
          react: { singleton: true, requiredVersion: false, eager: false },
          "react-dom": { singleton: true, requiredVersion: false, eager: false },
          "react-redux": { singleton: true, requiredVersion: false, eager: false },
          "@reduxjs/toolkit": { singleton: true, requiredVersion: false, eager: false },
          "@myapp/store": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
          "@myapp/api": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
          "@myapp/seo": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
        },
        extraOptions: {
          automaticAsyncBoundary: true,
        },
      })
    );
    return config;
  },
};

module.exports = nextConfig;

Remote Entry Path — React vs Next.js:

React MFE (ModuleFederationPlugin):
  filename: "remoteEntry.js"
  Served at: /products/remoteEntry.js
  Host loads: Products@https://dev.myapp.com/products/remoteEntry.js
  Same file for client and server — no SSR distinction.

Next.js MFE (NextFederationPlugin):
  filename: "static/chunks/remoteEntry.js"
  Served at: /content/_next/static/chunks/remoteEntry.js   (client)
             /content/_next/static/ssr/remoteEntry.js       (server)
  Host loads:
    Client: Content@https://dev.myapp.com/content/_next/static/chunks/remoteEntry.js
    Server: Content@https://dev.myapp.com/content/_next/static/ssr/remoteEntry.js

Why two paths?
  Next.js renders pages on the server (SSR) before sending HTML to the browser.
  The server needs a Node.js-compatible remoteEntry (no window, no DOM).
  The client needs a browser-compatible remoteEntry (with window, DOM access).
  NextFederationPlugin generates BOTH — the host picks the right one using isServer.

// next.config.js — isServer determines which remoteEntry to load
webpack(config, { isServer }) {
  config.plugins.push(
    new NextFederationPlugin({
      name: "Main",
      remotes: {
        // React remote — same remoteEntry for client AND server
        Auth: "Auth@https://dev.myapp.com/auth/remoteEntry.js",

        // Next.js remote — DIFFERENT remoteEntry for client vs server
        Content: `Content@https://dev.myapp.com/content/_next/static/${
          isServer ? "ssr" : "chunks"
        }/remoteEntry.js`,

        Products: `Products@https://dev.myapp.com/products/_next/static/${
          isServer ? "ssr" : "chunks"
        }/remoteEntry.js`,
      },
      // ...
    })
  );
}

// What happens at build time:
//
// 1. Next.js runs webpack TWICE — once for server, once for client.
//
// 2. Server build (isServer = true):
//    Content → loads /content/_next/static/ssr/remoteEntry.js
//    This entry is a CommonJS module that runs in Node.js.
//    It can access the filesystem, has no window or document.
//
// 3. Client build (isServer = false):
//    Content → loads /content/_next/static/chunks/remoteEntry.js
//    This entry is a browser script that attaches to window.
//    It uses the DOM, can access localStorage, runs in the browser.
//
// 4. React remotes (Auth, Cart) use the SAME remoteEntry.js
//    for both builds because they are client-only — the host
//    loads them with ssr: false via next/dynamic.

// WRONG — Using ModuleFederationPlugin path for Next.js remote
remotes: {
  Content: "Content@https://dev.myapp.com/content/remoteEntry.js",
  //                                             ^ WRONG PATH
  // This looks for remoteEntry.js at the content root — but
  // NextFederationPlugin places it at _next/static/chunks/remoteEntry.js.
  // Result: 404 Not Found. The host cannot load the Content remote.
}

// CORRECT — Using the Next.js _next/static path with isServer check
remotes: {
  Content: `Content@https://dev.myapp.com/content/_next/static/${
    isServer ? "ssr" : "chunks"
  }/remoteEntry.js`,
  //  _next/static/chunks/ for browser builds
  //  _next/static/ssr/ for server-side rendering
}

// WRONG — Using the same isServer path for React remotes
remotes: {
  Auth: `Auth@https://dev.myapp.com/auth/_next/static/${
    isServer ? "ssr" : "chunks"
  }/remoteEntry.js`,
  //                                    ^ WRONG
  // React MFEs don't have _next/static/ — they use plain webpack output.
  // Result: 404 Not Found. The host cannot load the Auth remote.
}

// CORRECT — React remotes use simple root-level remoteEntry.js
remotes: {
  Auth: "Auth@https://dev.myapp.com/auth/remoteEntry.js",
  //                                     ^ Simple path — no _next/static/
}

// next.config.js — extraOptions (NextFederationPlugin only)
new NextFederationPlugin({
  name: "Main",
  filename: "static/chunks/remoteEntry.js",
  remotes: { /* ... */ },
  shared: { /* ... */ },
  extraOptions: {
    // Expose all Next.js pages as federated modules automatically.
    // Without this, you must manually add each page to the exposes map.
    // The host can then import any page from the remote like a component.
    exposePages: true,

    // Fix next/image component when loaded from a federated remote.
    // Without this, images in remote components fail to resolve
    // because the image loader URL points to the host's domain
    // instead of the remote's domain.
    enableImageLoaderFix: true,

    // Fix static assets (fonts, SVGs) loaded via url-loader in remotes.
    // Without this, asset URLs resolve relative to the host's publicPath
    // instead of the remote's basePath — returning 404 for every asset.
    enableUrlLoaderFix: true,

    // Wrap exposed modules in an async boundary automatically.
    // This enables top-level await for shared dependency negotiation.
    // Without this, you must manually create an async bootstrap file
    // (the same bootstrap.js pattern used in React MFEs).
    automaticAsyncBoundary: true,
  },
});

// These options do NOT exist in ModuleFederationPlugin.
// React MFEs handle each of these manually:
//   - exposePages: not applicable (React has no pages directory)
//   - enableImageLoaderFix: not applicable (no next/image)
//   - enableUrlLoaderFix: handled by publicPath in webpack output
//   - automaticAsyncBoundary: requires manual bootstrap.js file

// Shared dependencies — React MFE vs Next.js MFE

// React MFE (ModuleFederationPlugin) — webpack.config.js
shared: {
  react: { singleton: true, requiredVersion: deps.react },
  "react-dom": { singleton: true, requiredVersion: deps["react-dom"] },
  "react-router-dom": { singleton: true, requiredVersion: deps["react-router-dom"] },
  "@reduxjs/toolkit": { singleton: true, requiredVersion: deps["@reduxjs/toolkit"] },
  "react-redux": { singleton: true, requiredVersion: deps["react-redux"] },
  "@myapp/store": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
  "@myapp/api": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
}

// Next.js MFE (NextFederationPlugin) — next.config.js
shared: {
  react: { singleton: true, requiredVersion: false, eager: false },
  "react-dom": { singleton: true, requiredVersion: false, eager: false },
  "react-redux": { singleton: true, requiredVersion: false, eager: false },
  "@reduxjs/toolkit": { singleton: true, requiredVersion: false, eager: false },
  "@myapp/store": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
  "@myapp/api": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
  "@myapp/seo": { singleton: true, strictVersion: true, requiredVersion: "1.0.0" },
}

// Key differences:
//
// 1. requiredVersion: false (Next.js) vs deps.react (React)
//    Next.js manages React versions internally — forcing a specific
//    version can conflict with Next.js's own React dependency.
//    React MFEs read the version from package.json to enforce matching.
//
// 2. eager: false is explicit in Next.js, implicit in React.
//    Both default to false, but Next.js configs set it explicitly
//    to prevent accidental eager loading that breaks SSR hydration.
//
// 3. react-router-dom is shared in React MFEs but NOT in Next.js.
//    Next.js uses its own next/router — no React Router needed.
//
// 4. @myapp/seo is shared in Next.js but not always in React MFEs.
//    SEO utilities (meta tags, structured data) only matter for
//    server-rendered pages — React SPAs handle SEO differently.