Code Splitting with lazy & Suspense

// STATIC import — resolved at build time.
// Chart.js and everything it imports goes INTO main.js.
import { Chart } from './Chart';

// DYNAMIC import() — a function call that returns a Promise.
// The bundler sees this and emits Chart (+ its dependencies)
// as a SEPARATE file: chart.[hash].chunk.js
const loadChart = () => import('./Chart');

// Nothing downloads until you actually call it:
loadChart().then((module) => {
  console.log('chunk arrived:', module.Chart);
});

WITHOUT code splitting
──────────────────────
main.js (2.1 MB)  ████████████████████████████████░ 4.8s
                                                    ▲ first paint here 😩

WITH code splitting
───────────────────
main.js (410 KB)  ██████░ 1.1s
                        ▲ first paint here 🎉
reports.chunk.js  ······ ███░ 0.6s   ← only when user opens /reports
editor.chunk.js   ·············· ██░ 0.4s   ← only when user starts writing

import { lazy } from 'react';

// lazy() takes a function that returns import()'s Promise.
// It must resolve to a module with a DEFAULT export
// that is a React component.
const GreetingCard = lazy(() => import('./GreetingCard'));

// From here, <GreetingCard /> works like a normal component —
// props and all. React just downloads its code on first render.

// ❌ One giant boundary: opening the chart blanks EVERYTHING
<Suspense fallback={<FullPageSpinner />}>
  <Header />
  <Sidebar />
  <SalesChart />   {/* lazy */}
</Suspense>

// ✅ Local boundary: header and sidebar stay put,
// only the chart area shows a skeleton
<Header />
<Sidebar />
<Suspense fallback={<ChartSkeleton />}>
  <SalesChart />   {/* lazy */}
</Suspense>

import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// Each page becomes its own chunk
const HomePage = lazy(() => import('./pages/HomePage'));
const ReportsPage = lazy(() => import('./pages/ReportsPage'));
const SettingsPage = lazy(() => import('./pages/SettingsPage'));
const AdminPage = lazy(() => import('./pages/AdminPage'));

export function App() {
  return (
    <BrowserRouter>
      {/* One boundary around the route outlet is enough:
          navigation swaps the whole page area anyway */}
      <Suspense fallback={<PageSkeleton />}>
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/reports" element={<ReportsPage />} />
          <Route path="/settings" element={<SettingsPage />} />
          <Route path="/admin" element={<AdminPage />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

import dynamic from 'next/dynamic';

// Same idea as lazy(), with the fallback built in
const SalesChart = dynamic(() => import('@/components/SalesChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // skip server-rendering for browser-only libs (canvas, window)
});

export default function ReportsPage() {
  return (
    <main>
      <h1>Reports</h1>
      <SalesChart />
    </main>
  );
}

const editorImport = () => import('./RichTextEditor');
const RichTextEditor = lazy(editorImport);

// 1. On hover / focus (shown in the demo)
<button onMouseEnter={editorImport} onFocus={editorImport}>
  Write a post
</button>

// 2. When the browser is idle after first paint
useEffect(() => {
  const id = requestIdleCallback(() => editorImport());
  return () => cancelIdleCallback(id); // cleanup if we unmount first
}, []); // run once after mount

// 3. When a trigger scrolls into view
useEffect(() => {
  const observer = new IntersectionObserver(([entry]) => {
    if (entry.isIntersecting) editorImport();
  });
  observer.observe(buttonRef.current);
  return () => observer.disconnect(); // always clean up observers
}, []); // observe once; the ref doesn't change

import { Component } from 'react';

// The one place classes still earn their keep in modern React
export class ChunkErrorBoundary extends Component {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error, info) {
    // Report to Sentry/monitoring — chunk failures spike after deploys
    console.error('Chunk failed to load:', error, info);
  }

  handleRetry = () => {
    // Clearing the error re-renders children → lazy retries the import
    this.setState({ hasError: false });
  };

  render() {
    if (this.state.hasError) {
      return (
        <div role="alert">
          <p>This section failed to load. Check your connection?</p>
          <button onClick={this.handleRetry}>Try again</button>
        </div>
      );
    }
    return this.props.children;
  }
}

import { lazy } from 'react';

export function lazyWithRetry(importFn, retries = 2) {
  return lazy(async () => {
    for (let attempt = 0; attempt <= retries; attempt++) {
      try {
        return await importFn();
      } catch (error) {
        if (attempt === retries) throw error; // let the boundary catch it
        // Back off: 1s, then 2s, then give up
        await new Promise((resolve) =>
          setTimeout(resolve, 1000 * (attempt + 1))
        );
      }
    }
  });
}

// Usage — drop-in replacement for lazy():
const SalesChart = lazyWithRetry(() => import('./SalesChart'));

export function ReportsSection() {
  return (
    <ChunkErrorBoundary>
      <Suspense fallback={<ChartSkeleton />}>
        <SalesChart />
      </Suspense>
    </ChunkErrorBoundary>
  );
}

// Chart.jsx uses a NAMED export:
export function Chart({ data }) { /* ... */ }

// ❌ BREAKS — lazy looks for module.default and finds undefined:
// "Element type is invalid: expected a string or a class/function
//  but got: undefined."
const Chart = lazy(() => import('./Chart'));

// ✅ FIX 1: map the named export to a default in .then()
const Chart = lazy(() =>
  import('./Chart').then((module) => ({ default: module.Chart }))
);

// ✅ FIX 2: give lazy-loaded components a default export
// Chart.jsx:
export default function Chart({ data }) { /* ... */ }
const Chart = lazy(() => import('./Chart'));

// Pull just the heavy DataGrid out of a component library
const DataGrid = lazy(() =>
  import('@my-org/ui-kit').then((module) => ({
    default: module.DataGrid,
  }))
);

// Careful: this only creates a separate chunk if the library
// is tree-shakeable (ESM). Otherwise the whole kit comes along.

npm run build
npx source-map-explorer 'dist/assets/*.js'

# Opens a treemap of every byte in the bundle, by source file.
# The biggest rectangles are your splitting candidates.
# (Vite alternative: npx vite-bundle-visualizer)

Route (app)                              Size     First Load JS
┌ ○ /                                    5.2 kB          92 kB
├ ○ /reports                             8.9 kB         101 kB
├ ○ /settings                            3.1 kB          89 kB
└ ○ /admin                               6.4 kB          95 kB
+ First Load JS shared by all            84 kB

# "First Load JS" is the number that matters for first paint.
# Before splitting the chart, /reports sat at 487 kB.

// ❌ BAD: new lazy component created on EVERY render —
// state inside SalesChart is destroyed each time, fallback flashes
function ReportsPage() {
  const SalesChart = lazy(() => import('./SalesChart'));
  return (
    <Suspense fallback={<ChartSkeleton />}>
      <SalesChart />
    </Suspense>
  );
}

// ✅ GOOD: declared once, at module scope
const SalesChart = lazy(() => import('./SalesChart'));

function ReportsPage() {
  return (
    <Suspense fallback={<ChartSkeleton />}>
      <SalesChart />
    </Suspense>
  );
}

// ❌ Serial: reports.chunk.js finishes → THEN chart.chunk.js starts
const ReportsPage = lazy(() => import('./ReportsPage'));
// inside ReportsPage.jsx:
const SalesChart = lazy(() => import('./SalesChart')); // renders on mount

// ✅ Parallel: warm both chunks when navigation starts
const reportsImport = () => import('./ReportsPage');
const chartImport = () => import('./SalesChart');

function ReportsLink() {
  const warmBoth = () => {
    reportsImport();
    chartImport(); // downloads side by side, not in sequence
  };
  return (
    <Link to="/reports" onMouseEnter={warmBoth} onFocus={warmBoth}>
      Reports
    </Link>
  );
}

// ❌ BAD: lazy component with no <Suspense> ancestor —
// React throws when the chunk hasn't arrived yet
function App() {
  return <SalesChart />;
}

// ✅ GOOD: every lazy component renders under a boundary
function App() {
  return (
    <Suspense fallback={<ChartSkeleton />}>
      <SalesChart />
    </Suspense>
  );
}