Mixing React and Next.js Micro Frontends Together: Hybrid Architecture Guide

# Hybrid Micro Frontend Architecture
# ────────────────────────────────────────────────────────
#
#   Browser
#     │
#     ▼
#   ┌─────────────────────────────────────────────────────┐
#   │  HOST — Main (Next.js + NextFederationPlugin)        │
#   │  Routes: /, /faq, /login, /bag, /products, /profile  │
#   │  Renders: server HTML  +  client hydration           │
#   └─────────────────────────────────────────────────────┘
#     │                                          │
#     │  ssr: false (client only)                │  isServer ternary
#     ▼                                          ▼
#   ┌──────────────────┐                ┌────────────────────────┐
#   │  React Remotes   │                │  Next.js Remotes       │
#   │  (ModuleFedPlug) │                │  (NextFederationPlug)  │
#   │                  │                │                        │
#   │  Auth     /auth  │                │  Products  /products   │
#   │  Cart     /cart  │                │  Content   /content    │
#   │  Account  /acct  │                │                        │
#   │  Support  /supp  │                │  basePath + assetPrefix│
#   │                  │                │  Two remoteEntry files │
#   │  ONE remoteEntry │                │  /ssr/ + /chunks/      │
#   │  /remoteEntry.js │                │                        │
#   └──────────────────┘                └────────────────────────┘
#
# Key Insight:
# A single Next.js host can load BOTH plugin types simultaneously.
# The remote URL pattern tells you which plugin built each remote:
#   - Plain /remoteEntry.js → React (ModuleFederationPlugin)
#   - /_next/static/.../remoteEntry.js → Next.js (NextFederationPlugin)

// apps/Main/next.config.js — Next.js host loading BOTH React and Next.js remotes
const { NextFederationPlugin } = require('@module-federation/nextjs-mf');
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
  disable: process.env.NODE_ENV === 'development',
});

module.exports = withBundleAnalyzer(
  withPWA({
    reactStrictMode: false,
    output: 'standalone',
    transpilePackages: ['@myapp/seo', '@myapp/store', '@myapp/api'],

    webpack(config, { isServer }) {
      // Exclude Node.js core modules from browser bundle
      if (!isServer) {
        config.resolve.fallback = {
          ...config.resolve.fallback,
          fs: false,
          stream: false,
          zlib: false,
        };
      }

      config.plugins.push(
        new NextFederationPlugin({
          name: 'Main',
          filename: 'static/chunks/remoteEntry.js',
          remotes: {
            // React remotes — ModuleFederationPlugin output (browser-only)
            // ONE remoteEntry.js file at root of the served path
            Auth:    'Auth@https://dev.myapp.com/auth/remoteEntry.js',
            Account: 'Account@https://dev.myapp.com/account/remoteEntry.js',
            Cart:    'Cart@https://dev.myapp.com/cart/remoteEntry.js',
            Support: 'Support@https://dev.myapp.com/support/remoteEntry.js',

            // Next.js remotes — NextFederationPlugin output (dual build)
            // TWO remoteEntry.js files — isServer picks the right one
            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`,
          },
          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: {
            exposePages: true,
            enableImageLoaderFix: true,
            enableUrlLoaderFix: true,
            automaticAsyncBoundary: true,
          },
        })
      );

      return config;
    },
  })
);

// Why this works:
// NextFederationPlugin understands BOTH remote URL patterns.
// React remotes loaded via plain remoteEntry.js — no dual build needed
// since ssr: false in next/dynamic skips them on the server.
// Next.js remotes loaded via the /ssr/ vs /chunks/ ternary so each
// webpack pass picks the matching entry.

// apps/Main/pages/login/index.tsx — Host page consuming a REACT remote
import dynamic from 'next/dynamic';
import { Suspense } from 'react';
import { useRouter } from 'next/navigation';

// Dynamic import of remote Login component
//   Auth/Login   → resolves to https://dev.myapp.com/auth/remoteEntry.js
//                  → exposes './Login' from src/components/Login.jsx
const RemoteLogin = dynamic(
  () => import('Auth/Login'),
  {
    loading: () => <LoadingState />,
    ssr: false,                            // <- Required: React remote has NO ssr/ entry
  }
);

function LoadingState() {
  return (
    <div style={styles.loading}>
      <div style={styles.spinner}></div>
      <p>Loading Login...</p>
    </div>
  );
}

export default function LoginPage() {
  const router = useRouter();

  // Bridge function — the React remote does NOT use Next.js router.
  // It calls back into the host with a path string + state, and the
  // host's useRouter pushes the new route. This keeps the React remote
  // framework-agnostic and reusable in non-Next.js hosts.
  const handleNavigate = (path: string, state?: any) => {
    if (state?.mobileNumber) {
      sessionStorage.setItem('mobileNumber', state.mobileNumber);
    }
    router.push(path);
  };

  return (
    <div style={styles.container}>
      <div style={styles.content}>
        <Suspense fallback={<LoadingState />}>
          <RemoteLogin onNavigate={handleNavigate} />
        </Suspense>
      </div>
    </div>
  );
}

// Why React remotes need a bridge function:
// 1. The Auth MFE was originally built for a React-only host (no Next.js)
// 2. It cannot import next/navigation — it would break the React-only build
// 3. The host owns routing — passes a callback into the remote via props
// 4. This pattern lets the SAME Auth remote work in any host framework

// apps/Main/pages/faq/index.tsx — Host page consuming a NEXT.JS remote
import dynamic from 'next/dynamic';
import { Suspense } from 'react';
import Head from 'next/head';

// Content/FAQ → resolves to /content/_next/static/{ssr|chunks}/remoteEntry.js
//             → exposes './FAQ' from components/FAQ
const RemoteFAQ = dynamic(
  () => import('Content/FAQ'),
  {
    loading: () => <LoadingState />,
    ssr: false,                            // <- Required even for Next.js remotes
  }
);

function LoadingState() {
  return (
    <div style={styles.loading}>
      <div style={styles.spinner}></div>
      <p>Loading FAQs...</p>
    </div>
  );
}

export default function FAQPage() {
  return (
    <>
      <Head>
        <title>Frequently Asked Questions | MyApp</title>
        <meta name="description" content="Find answers to common questions" />
      </Head>
      <div style={styles.container}>
        <div style={styles.content}>
          <Suspense fallback={<LoadingState />}>
            <RemoteFAQ />
          </Suspense>
        </div>
      </div>
    </>
  );
}

// Why ssr: false for the Next.js remote too?
// Even though Content has an /ssr/ remoteEntry.js, the host loads it with
// ssr: false because the FAQ component reads from the shared Redux store
// (window-only) and uses useEffect for data fetching. Setting ssr: true
// would still trigger client-side hydration mismatch the moment Redux
// initializes. The /ssr/ entry exists for cases where Next.js needs to
// import the federated MODULE during the server build — not because the
// component itself renders on the server.

# Shared Dependencies Across Both Remote Types
# ────────────────────────────────────────────
#
# Module Federation enforces dependency singletons via the 'shared' config.
# When the host loads two remotes built with DIFFERENT plugins, the runtime
# still negotiates a single instance for each shared package.
#
# Negotiation Sequence:
#   1. Host boots → loads its own React, react-redux, @myapp/store
#   2. Host requests Auth/Login → fetches /auth/remoteEntry.js
#      → Auth's shared registry says: 'I need react ^18.2 (singleton)'
#      → Host registry: 'I have react 18.2.0' → reuse host's React
#   3. Host requests Content/FAQ → fetches /content/_next/static/chunks/remoteEntry.js
#      → Content's shared registry says: 'I need react (singleton, no version)'
#      → Host registry: 'I have react 18.2.0' → reuse host's React
#
# Critical rules for hybrid setups:
#
# 1. Same package names everywhere
#    - Both React remote AND Next.js remote share '@myapp/store' (NOT '@myapp/shared-store')
#    - Webpack matches strings literally — a typo creates a duplicate instance
#
# 2. Same major version
#    - All remotes share react: 18.x
#    - Mixing 17.x and 18.x produces: 'Invalid hook call' or hydration crashes
#
# 3. eager: false everywhere
#    - Both ModuleFederationPlugin and NextFederationPlugin require eager: false
#    - Eager loading bypasses the singleton negotiation → duplicate React instances
#
# 4. strictVersion: true for in-house packages
#    - @myapp/store, @myapp/api use strictVersion + requiredVersion: '1.0.0'
#    - Forces every remote to use EXACTLY 1.0.0 — no silent drift between deploys
#
# 5. requiredVersion: false for framework deps
#    - react, react-dom, react-redux use requiredVersion: false
#    - Lets the host's installed version win — matches whatever Next.js bundles

// packages/store/src/index.js — Singleton Redux store shared by both remote types
import { configureStore } from '@reduxjs/toolkit';
import authReducer from './slices/authSlice';
import cartReducer from './slices/cartSlice';
import productsReducer from './slices/productsSlice';

export const store = configureStore({
  reducer: {
    auth:     authReducer,
    cart:     cartReducer,
    products: productsReducer,
  },
});

export { Provider } from 'react-redux';
export { useSelector, useDispatch } from 'react-redux';
export * from './slices/authSlice';
export * from './slices/cartSlice';
export * from './slices/productsSlice';

// HOW BOTH REMOTE TYPES USE THIS STORE
// ────────────────────────────────────
//
// React remote (apps/Auth/src/components/Login.jsx):
//   import { useSelector, useDispatch, setUser } from '@myapp/store';
//
// Next.js remote (apps/Products/components/BeautyCare.tsx):
//   import { useSelector, useDispatch, addToCart } from '@myapp/store';
//
// Both imports resolve to the SAME singleton instance because:
// 1. Both webpack configs declare '@myapp/store' as a singleton
// 2. The host creates the store ONCE in ClientReduxProvider
// 3. Module Federation negotiates: 'There is already a @myapp/store loaded'
// 4. Every remote gets the host's store instance — not their own copy
//
// If a remote accidentally creates a second store:
//   - Login dispatches setUser → updates store A
//   - BeautyCare reads useSelector → reads store B (empty)
//   - User sees 'Not logged in' even after login → bug

# /etc/nginx/sites-available/myapp.conf — Reverse proxy for hybrid MFE
server {
  listen 443 ssl http2;
  server_name dev.myapp.com;

  # ── React remotes — static files, served directly by Nginx ──
  location /auth/ {
    alias /var/www/myapp/auth/;
    add_header Access-Control-Allow-Origin "*" always;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
    try_files $uri $uri/ =404;
  }

  location /cart/ {
    alias /var/www/myapp/cart/;
    add_header Access-Control-Allow-Origin "*" always;
    try_files $uri $uri/ =404;
  }

  location /account/ {
    alias /var/www/myapp/account/;
    add_header Access-Control-Allow-Origin "*" always;
    try_files $uri $uri/ =404;
  }

  location /support/ {
    alias /var/www/myapp/support/;
    add_header Access-Control-Allow-Origin "*" always;
    try_files $uri $uri/ =404;
  }

  # ── Next.js remotes — proxy to Node.js process (basePath isolated) ──
  location /products/ {
    proxy_pass http://127.0.0.1:3001;        # PM2-managed Products server
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto https;
    proxy_http_version 1.1;
  }

  location /content/ {
    proxy_pass http://127.0.0.1:3002;        # PM2-managed Content server
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto https;
    proxy_http_version 1.1;
  }

  # ── Host (Main) — catch-all for everything else ──
  location / {
    proxy_pass http://127.0.0.1:3000;        # PM2-managed Main host
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto https;
    proxy_http_version 1.1;
  }
}

# How the request flow works:
#   GET /                  → Main (Next.js host) → renders home page HTML
#   GET /faq               → Main → loads Content/FAQ remote at runtime
#   GET /content/_next/... → Content remote (Node.js)
#   GET /login             → Main → loads Auth/Login remote at runtime
#   GET /auth/remoteEntry.js → Nginx serves static file directly

# Common Pitfalls When Mixing React + Next.js Remotes
# ────────────────────────────────────────────────────
#
# 1. Forgetting the isServer ternary for Next.js remotes
#    WRONG: Content: 'Content@/content/remoteEntry.js'
#    Why it breaks:
#      - Server build fetches a browser-compatible entry → window is undefined
#      - Build crashes with: 'ReferenceError: window is not defined'
#    FIX: Use the isServer ternary from the host config example above
#
# 2. Adding the isServer ternary to React remote URLs
#    WRONG: Auth: `Auth@/auth/_next/static/${isServer ? 'ssr' : 'chunks'}/remoteEntry.js`
#    Why it breaks:
#      - React remotes have NO _next/static/ssr/ folder — that path 404s
#      - Server build fails to fetch the SSR entry
#    FIX: Plain URL only — Auth: 'Auth@/auth/remoteEntry.js'
#
# 3. Forgetting basePath on a Next.js remote
#    WRONG: Products without basePath/assetPrefix
#    Why it breaks:
#      - Static assets at /_next/static/chunks/ collide with the host's
#      - Two MFEs both write 'main-abc.js' to the same path
#      - First one wins, the other returns the wrong code
#    FIX: Always set basePath AND assetPrefix to a unique path per remote
#
# 4. Mixing React versions across remotes
#    WRONG: Auth uses react 17.0.2, Products uses react 18.2.0
#    Why it breaks:
#      - Singleton negotiation picks ONE version → other remote gets wrong API
#      - Hooks throw 'Invalid hook call' or 'rendered fewer hooks'
#    FIX: Lock react version in root package.json — every workspace pulls same version
#
# 5. Trying to use Next.js APIs inside a React remote
#    WRONG: import { useRouter } from 'next/navigation' inside Auth remote
#    Why it breaks:
#      - Auth has no Next.js dependency — webpack throws 'Module not found'
#      - Even if installed, useRouter has no Next.js context outside the host
#    FIX: Use the bridge pattern — host passes onNavigate prop to React remote
#
# 6. Calling next/image inside a Next.js remote when host is a React MFE
#    WRONG: next/image without enableImageLoaderFix
#    Why it breaks:
#      - next/image relies on Next.js image optimization endpoint at /_next/image
#      - The endpoint exists only on the Next.js host — React MFE has no /_next/image
#    FIX: enableImageLoaderFix: true in extraOptions of every Next.js remote
#
# 7. Using next/router inside a Next.js remote that also runs standalone
#    Why it works in some setups and breaks others:
#      - When loaded as a remote, the host owns the router context
#      - When the remote runs standalone for testing, it has its own router
#      - Code that depends on router presence breaks intermittently
#    FIX: Wrap router calls in try/catch OR use props for cross-MFE navigation
#
# 8. Hard-coding remote URLs without environment switching
#    Why it breaks deployment:
#      - Local dev: https://localhost:4101/remoteEntry.js
#      - Prod: https://dev.myapp.com/auth/remoteEntry.js
#      - One config wired to localhost crashes in production
#    FIX: Read remote URLs from process.env.NEXT_PUBLIC_AUTH_URL etc.