SSR vs CSR in Next.js Module Federation Explained

# Next.js runs webpack TWICE for every build

# Build 1 — Server (Node.js)
#   isServer = true
#   Output: .next/server/
#   Purpose: render HTML on the server before sending to browser
#   Environment: Node.js — has fs, http, process — NO window, NO document

# Build 2 — Client (Browser)
#   isServer = false
#   Output: .next/static/chunks/
#   Purpose: hydrate server HTML and handle interactivity
#   Environment: Browser — has window, document, localStorage — NO fs, NO process

# Module Federation must work in BOTH builds.
# That means two separate remoteEntry.js files:
#
#   .next/static/ssr/remoteEntry.js       ← Node.js compatible (Build 1)
#   .next/static/chunks/remoteEntry.js    ← Browser compatible (Build 2)
#
# React MFEs (ModuleFederationPlugin) only produce ONE remoteEntry.js
# because they run exclusively in the browser — no server build exists.

// apps/Main/next.config.js — isServer selects the correct remoteEntry
webpack(config, { isServer }) {
  config.plugins.push(
    new NextFederationPlugin({
      name: 'Main',
      filename: 'static/chunks/remoteEntry.js',
      remotes: {
        // React remotes — ONE remoteEntry.js (browser only)
        // No isServer check needed — loaded with ssr: false
        Auth: 'Auth@https://dev.myapp.com/auth/remoteEntry.js',
        Cart: 'Cart@https://dev.myapp.com/cart/remoteEntry.js',
        Account: 'Account@https://dev.myapp.com/account/remoteEntry.js',
        Support: 'Support@https://dev.myapp.com/support/remoteEntry.js',

        // Next.js remotes — TWO remoteEntry.js files (server + browser)
        // isServer picks the correct one for each webpack build
        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;
}

// pages/faq/index.tsx — Loading a Next.js remote with ssr: false
import dynamic from 'next/dynamic';
import { Suspense } from 'react';

const RemoteFAQ = dynamic(
  () => import('Content/FAQ'),
  {
    loading: () => <div className="shimmer" />,
    ssr: false,
  }
);

export default function FAQPage() {
  return (
    <Suspense fallback={<div className="shimmer" />}>
      <RemoteFAQ />
    </Suspense>
  );
}

// What happens at each phase:
//
// SERVER PHASE (Node.js):
//   1. Next.js receives GET /faq
//   2. It renders FAQPage on the server
//   3. RemoteFAQ has ssr: false → server SKIPS it entirely
//   4. Server renders the loading fallback (<div className="shimmer" />)
//   5. Server sends HTML with the shimmer placeholder to the browser
//
// CLIENT PHASE (Browser):
//   1. Browser receives HTML with shimmer placeholder
//   2. React hydrates the page — shimmer is already in the DOM
//   3. After hydration, next/dynamic triggers the Module Federation import
//   4. Browser fetches /content/_next/static/chunks/remoteEntry.js
//   5. remoteEntry.js resolves the FAQ component
//   6. React replaces the shimmer with the actual FAQ component
//   7. FAQ component calls useEffect → fetches data from API → renders

// apps/Main/pages/_app.tsx — Every wrapper uses ssr: false
import React from 'react';
import type { AppProps } from 'next/app';
import dynamic from 'next/dynamic';
import '../styles/globals.css';

// Layout — header, footer, sidebar (uses window for responsive breakpoints)
const Layout = dynamic(() => import('../components/Layout'), {
  ssr: false,
  loading: () => <div className="shimmer" />,
});

// Redux Provider — creates the singleton store (client-only)
const ClientReduxProvider = dynamic(
  () => import('../components/ClientReduxProvider'),
  { ssr: false, loading: () => null }
);

// Auth — checks refresh token, restores session (needs localStorage)
const InitiateAuth = dynamic(() => import('../components/InitiateAuth'), {
  ssr: false,
  loading: () => null,
});

// Route guard — blocks unauthenticated access (reads Redux auth state)
const ProtectedRoute = dynamic(
  () => import('../components/Security/ProtectedRoute'),
  { ssr: false, loading: () => null }
);

// Analytics — tracks page views (needs window.gtag)
const GoogleAnalytics = dynamic(
  () => import('../components/GoogleAnalytics'),
  { ssr: false, loading: () => null }
);

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClientReduxProvider>
      <InitiateAuth />
      <GoogleAnalytics />
      <ProtectedRoute>
        <Layout>
          <Component {...pageProps} />
        </Layout>
      </ProtectedRoute>
    </ClientReduxProvider>
  );
}

export default MyApp;

// Why ssr: false on EVERYTHING?
//
// 1. ClientReduxProvider uses window to check auth state on mount
// 2. InitiateAuth reads localStorage for refresh tokens
// 3. ProtectedRoute reads Redux store (populated by InitiateAuth)
// 4. Layout uses window.innerWidth for responsive breakpoints
// 5. GoogleAnalytics calls window.gtag
//
// None of these can run on the server. If ssr were true,
// the server build would crash with "window is not defined".

# Complete rendering timeline: SSR + CSR with Module Federation

# Phase 1 — Server-Side Rendering (Node.js)
# ──────────────────────────────────────────
# 1. Browser requests GET /faq
# 2. Next.js server receives the request
# 3. Server runs getStaticProps (if any) — fetches static data
# 4. Server starts rendering the React component tree
# 5. It reaches <RemoteFAQ /> with ssr: false
# 6. Server renders the LOADING FALLBACK instead of the component
#    Output: <div class="shimmer"></div>
# 7. Server sends complete HTML to browser
#    → Fast First Contentful Paint (user sees shimmer + layout)

# Phase 2 — Hydration (Browser)
# ──────────────────────────────────────────
# 8.  Browser receives HTML and paints it immediately
# 9.  Browser downloads the client JavaScript bundle
# 10. React hydration starts — attaches event listeners to existing HTML
# 11. Hydration matches server HTML node-by-node
# 12. RemoteFAQ (ssr: false) was not in server HTML — React skips it
# 13. Hydration completes — page is now interactive

# Phase 3 — Remote Component Loading (Browser)
# ──────────────────────────────────────────
# 14. next/dynamic triggers the Module Federation import
# 15. Browser fetches /content/_next/static/chunks/remoteEntry.js
# 16. remoteEntry.js registers the Content container
# 17. Module Federation negotiates shared dependencies (React, Redux)
# 18. Browser fetches the FAQ component chunk
# 19. FAQ component mounts and runs useEffect
# 20. useEffect calls the API → fetches FAQ data
# 21. FAQ data arrives → component re-renders with content
# 22. Shimmer is replaced with the fully rendered FAQ

# Total user experience:
#   0ms:    White screen (HTML downloading)
#   ~200ms: Layout + shimmer visible (server HTML painted)
#   ~500ms: Page interactive (hydration complete)
#   ~800ms: Remote component appears (remoteEntry fetched)
#   ~1200ms: FAQ data displayed (API response rendered)

// pages/beautycare/index.tsx — Remote loading with error boundary
import dynamic from 'next/dynamic';
import { Suspense } from 'react';
import ErrorBoundary from '../../components/ErrorBoundary';

const RemoteBeautyCare = dynamic(
  () => import('Products/BeautyCare').catch(() => {
    return { default: () => <div>Products service is temporarily unavailable.</div> };
  }),
  {
    loading: () => <div className="shimmer" />,
    ssr: false,
  }
);

export default function BeautyCarePage() {
  return (
    <ErrorBoundary>
      <Suspense fallback={<div className="shimmer" />}>
        <RemoteBeautyCare />
      </Suspense>
    </ErrorBoundary>
  );
}

// Error handling layers:
//
// Layer 1 — .catch() on import:
//   If remoteEntry.js fails to load (404, network error, timeout),
//   the catch returns a fallback component instead of crashing.
//
// Layer 2 — ErrorBoundary:
//   If the remote component throws during rendering (null reference,
//   missing data, API error), the ErrorBoundary catches it and
//   displays a recovery UI with a "Reload" button.
//
// Layer 3 — Suspense fallback:
//   While the remote is loading, the shimmer placeholder displays.
//   If the remote loads but suspends (e.g., lazy subcomponents),
//   Suspense shows the fallback until everything resolves.

// PROBLEM: Hydration mismatch when remote renders different content
// on server vs client

// Server renders:
<div class="shimmer"></div>   <!-- ssr: false → loading fallback -->

// Client hydrates and then replaces with:
<div class="faq-container">
  <h2>Frequently Asked Questions</h2>
  <div class="faq-item">...</div>
</div>

// This is NOT a hydration mismatch because ssr: false tells React
// "this component does not exist in the server HTML."
// React knows to mount it fresh on the client — no comparison needed.

// REAL hydration mismatch happens when:
// 1. A component renders on the server AND the client
// 2. The server output differs from the client output
//
// Example of what WOULD cause a mismatch:
//   Server: <p>Current time: 10:30:00 AM</p>
//   Client: <p>Current time: 10:30:01 AM</p>
//
// The fix: use ssr: false for any component whose output depends on
// browser-only state (time, localStorage, window size, auth tokens).

// With Module Federation remotes, ssr: false is ALWAYS the correct choice
// because remote components:
//   - Attach to window (which doesn't exist on the server)
//   - Read from localStorage/sessionStorage for auth state
//   - Use browser APIs (IntersectionObserver, ResizeObserver, etc.)
//   - Fetch data client-side via useEffect + API calls

// Why eager: false is critical for SSR in Next.js

// WRONG — eager: true breaks hydration
shared: {
  react: { singleton: true, requiredVersion: false, eager: true },
}
// What happens:
// 1. Server renders HTML using its own React instance
// 2. Browser starts hydration with the SAME React instance
// 3. eager: true loads a SECOND React instance synchronously
//    during webpack chunk evaluation (before hydration finishes)
// 4. Two React instances exist simultaneously
// 5. Hydration fails: "Cannot read properties of null"
//    or "Rendered fewer hooks than expected"

// CORRECT — eager: false defers loading until needed
shared: {
  react: { singleton: true, requiredVersion: false, eager: false },
}
// What happens:
// 1. Server renders HTML using its own React instance
// 2. Browser starts hydration with the server's React
// 3. Module Federation's async negotiation runs AFTER hydration
// 4. The singleton check finds React already loaded — reuses it
// 5. One React instance throughout the entire lifecycle
// 6. No hydration mismatch, no duplicate instances

// This is why EVERY shared dependency in Next.js must use eager: false.
// React MFEs can sometimes use eager: true because they have no
// server-rendered HTML to hydrate against — there is no SSR phase.

// pages/index.tsx — SSR data fetching on the HOST (not remotes)
import { GetStaticProps } from 'next';
import dynamic from 'next/dynamic';

// Remote MFE — loaded client-side only
const RemoteProducts = dynamic(
  () => import('Products/CategoryPage'),
  { ssr: false, loading: () => <div className="shimmer" /> }
);

interface HomePageProps {
  bannerData: { title: string; image: string }[];
  timestamp: number;
}

export default function HomePage({ bannerData, timestamp }: HomePageProps) {
  return (
    <div>
      {/* SSR content — rendered on the server as static HTML */}
      <section className="hero-banner">
        {bannerData.map((banner, i) => (
          <div key={i}>
            <h2>{banner.title}</h2>
            <img src={banner.image} alt={banner.title} />
          </div>
        ))}
      </section>

      {/* CSR content — remote loads after hydration */}
      <section className="product-grid">
        <RemoteProducts />
      </section>
    </div>
  );
}

// getStaticProps runs at BUILD TIME on the server.
// It fetches data that becomes part of the static HTML.
// Remote components are NOT involved — they load client-side.
export const getStaticProps: GetStaticProps<HomePageProps> = async () => {
  const response = await fetch('https://api.myapp.com/banners');
  const bannerData = await response.json();

  return {
    props: {
      bannerData: bannerData.data,
      timestamp: Date.now(),
    },
    revalidate: 300, // ISR: regenerate every 5 minutes
  };
};

// This creates a HYBRID page:
//   - Banner section: SSR (pre-rendered HTML, fast First Contentful Paint)
//   - Products section: CSR (loads after hydration, shows shimmer first)
//
// The remote component NEVER runs during getStaticProps.
// Module Federation imports only execute in the browser (ssr: false).

// Remote component: apps/Content/components/FAQ.tsx
// This runs INSIDE the Content remote MFE — loaded by the host
import { useState, useEffect } from 'react';
import { getFAQData } from '@myapp/api';

export default function FAQ() {
  const [faqData, setFaqData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // Data fetching happens client-side via useEffect
  // NOT via getServerSideProps or getStaticProps
  useEffect(() => {
    const fetchData = async () => {
      try {
        setLoading(true);
        const response = await getFAQData('active');
        setFaqData(response.data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, []);

  if (loading) return <div className="shimmer" />;
  if (error) return <div className="error">{error}</div>;

  return (
    <div className="faq-container">
      {faqData.map((item) => (
        <details key={item.id}>
          <summary>{item.question}</summary>
          <p>{item.answer}</p>
        </details>
      ))}
    </div>
  );
}

// Why useEffect and not getServerSideProps?
//
// 1. This component is EXPOSED via Module Federation (exposes: { './FAQ': ... })
// 2. The host loads it with ssr: false — it never runs on the server
// 3. getServerSideProps only works for PAGE components in the pages/ directory
// 4. Exposed components are regular React components, not Next.js pages
// 5. They cannot use Next.js data fetching methods (getStaticProps, etc.)
//
// This is the standard pattern for ALL remote MFE components:
//   Mount → useEffect → fetch API → render data

// components/ClientReduxProvider.tsx — Client-only Redux wrapper
'use client';
import { ReactNode } from 'react';
import { Provider, store } from '@myapp/store';

interface ClientReduxProviderProps {
  children: ReactNode;
}

export default function ClientReduxProvider({ children }: ClientReduxProviderProps) {
  return (
    <Provider store={store}>
      {children}
    </Provider>
  );
}

// 'use client' marks this as a Client Component.
// The Redux store is a singleton shared via Module Federation.
// Every remote MFE that imports @myapp/store gets the SAME instance.
//
// Why this CANNOT run on the server:
//   1. The store reads localStorage for persisted auth tokens
//   2. Redux devtools extension attaches to window.__REDUX_DEVTOOLS__
//   3. The store singleton must be created ONCE in the browser
//   4. If created on the server, each request would share state
//      between different users — a critical security vulnerability

// Remote component with browser API guards
// apps/Products/pages/products/[productNumericId].tsx

const handleBuyNow = () => {
  handleAddToCart();
  // Guard: typeof window check prevents server crash
  if (typeof window !== 'undefined') {
    return handleNavigate('/bag');
  }
};

// Guest cart service — 100% client-side storage
const isLocalStorageAvailable = () => {
  try {
    const test = '__storage_test__';
    localStorage.setItem(test, test);
    localStorage.removeItem(test);
    return true;
  } catch (e) {
    return false;
  }
};

// Why typeof window checks still matter with ssr: false:
//
// 1. The MODULE is bundled into both server and client builds
//    even if the COMPONENT is loaded with ssr: false
// 2. Tree-shaking might not eliminate all browser-only code paths
// 3. If the module is accidentally imported without ssr: false,
//    the typeof window guard prevents a server crash
// 4. It's defensive coding — the guard costs nothing but prevents
//    hard-to-debug "window is not defined" errors in production

// Next.js remote — automaticAsyncBoundary replaces bootstrap.js

// React MFE approach (manual bootstrap.js):
// index.js
import('./bootstrap');

// bootstrap.js — async entry point
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
ReactDOM.render(<App />, document.getElementById('root'));

// The separate bootstrap.js file forces webpack to load shared
// dependencies asynchronously before the app mounts.
// Without it, shared dependency negotiation fails.


// Next.js MFE approach (automaticAsyncBoundary: true):
// next.config.js
new NextFederationPlugin({
  name: 'Content',
  filename: 'static/chunks/remoteEntry.js',
  exposes: {
    './FAQ': './components/FAQ',
  },
  extraOptions: {
    automaticAsyncBoundary: true,
  },
});

// NextFederationPlugin wraps EVERY exposed module in an async boundary
// automatically — no bootstrap.js file needed.
//
// What it generates internally:
//   export default () => import('./components/FAQ');
//
// This ensures shared dependencies are negotiated asynchronously
// before the component code executes.
//
// Benefits over manual bootstrap.js:
// 1. No extra file to maintain
// 2. Works with Next.js's own code splitting
// 3. Compatible with both SSR and CSR builds
// 4. Each exposed module gets its own boundary (not one for the entire app)