📦 Code Splitting and Lazy Loading

The Monolithic Bundle Problem

As an app grows, a naive build packs every component, library, and helper into one large JavaScript file. The browser must download, parse, and execute all of it before the user can interact — even code for pages they may never visit.

It's like being forced to buy every item in the grocery store just to get a carton of milk. The user pays the cost of the whole app to use a fraction of it, and on a slow phone connection that cost is measured in seconds of blank screen.

What Is Code Splitting?

Code splitting breaks your app into chunks that load on demand or in parallel. The browser fetches a small entry chunk to render the first view fast, then pulls in additional chunks as the user navigates or triggers features.

Think of it like reading a book chapter by chapter instead of memorizing the whole thing before you can start. You process only what's relevant to the current moment.

React.lazy and Suspense

The engine under code splitting is the dynamic import() expression, which returns a promise for a module and signals the bundler to emit a separate chunk. React.lazy wraps a dynamic import so you can render the result as an ordinary component.

Without lazy loading, a component is imported statically and always ends up in the main bundle:

// Eager: ExpensiveComponent ships in the main bundle, always
import ExpensiveComponent from './ExpensiveComponent';

function App({ showExpensive }) {
  return (
    <div>
      <Header />
      {showExpensive && <ExpensiveComponent />}
    </div>
  );
}

With lazy and Suspense, the chunk is fetched only the first time the component renders, and Suspense shows a fallback while it loads:

import { lazy, Suspense } from 'react';

const ExpensiveComponent = lazy(() => import('./ExpensiveComponent'));

function App({ showExpensive }) {
  return (
    <div>
      <Header />
      {showExpensive && (
        <Suspense fallback={<div>Loading…</div>}>
          <ExpensiveComponent />
        </Suspense>
      )}
    </div>
  );
}

A single Suspense can wrap several lazy components. They download in parallel, and the fallback shows until all of them are ready:

import { lazy, Suspense } from 'react';

const Panel = lazy(() => import('./Panel'));
const Sidebar = lazy(() => import('./Sidebar'));

function Layout() {
  return (
    <Suspense fallback={<div>Loading…</div>}>
      <Sidebar />
      <Panel />
    </Suspense>
  );
}

Route-Based Splitting

The highest-value split is by route: each page becomes its own chunk, so visiting / never downloads the analytics dashboard. This example uses React Router v6 (current API — Routes and the element prop, not the old Switch/component):

import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Header from './Header';   // eager: needed on every page
import Footer from './Footer';

const Home = lazy(() => import('./routes/Home'));
const Dashboard = lazy(() => import('./routes/Dashboard'));
const Products = lazy(() => import('./routes/Products'));
const Analytics = lazy(() => import('./routes/Analytics'));

function App() {
  return (
    <BrowserRouter>
      <Header />
      <Suspense fallback={<div className="loading">Loading…</div>}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/products" element={<Products />} />
          <Route path="/analytics" element={<Analytics />} />
        </Routes>
      </Suspense>
      <Footer />
    </BrowserRouter>
  );
}

Component-Based Splitting

Beyond routes, split heavy or rarely-used components so their weight never touches users who don't open them. Good candidates:

• Modals and dialogs not shown to every user (a size chart, a confirmation flow)
• Heavy widgets — rich text editors, maps, charting libraries
• Feature-gated areas — admin panels, settings pages
• Third-party integrations — payment forms, chat widgets

import { lazy, Suspense, useState } from 'react';

const ComplexChart = lazy(() => import('./ComplexChart'));

function Dashboard() {
  const [showChart, setShowChart] = useState(false);

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={() => setShowChart(true)}>Show Performance Chart</button>

      {showChart && (
        <Suspense fallback={<div>Loading chart…</div>}>
          <ComplexChart />
        </Suspense>
      )}
    </div>
  );
}

The chart's library (often hundreds of kilobytes) only downloads when a user actually clicks the button — most visitors never pay for it.

Error Boundaries for Lazy Loads

A dynamic import can fail — a flaky network, a deploy that removed the old chunk. Suspense handles the loading state, but not errors. Wrap lazy components in an error boundary so a failed chunk shows a graceful message instead of crashing the app.

import { Component } from 'react';

class ErrorBoundary extends Component {
  state = { hasError: false };

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

  componentDidCatch(error, info) {
    console.error('Lazy load failed:', error, info);
    // report to your error-tracking service here
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? <p>Something went wrong loading this section.</p>;
    }
    return this.props.children;
  }
}

Compose the boundary outside the Suspense so it can catch both load failures and render errors:

import { lazy, Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const Reviews = lazy(() => import('./Reviews'));

function ReviewsSection() {
  return (
    <ErrorBoundary fallback={<div>Couldn't load reviews. Please retry later.</div>}>
      <Suspense fallback={<div>Loading reviews…</div>}>
        <Reviews />
      </Suspense>
    </ErrorBoundary>
  );
}

Prefetching: Loading Just Before It's Needed

Lazy loading has one downside: the first time a user opens a lazy view, they wait for the chunk. Prefetching hides that delay by fetching the chunk ahead of the click — for example when the user hovers a link — so it's already cached when they navigate. It's like pre-loading the next episode while the current one plays.

import { useRef } from 'react';
import { Link } from 'react-router-dom';

// Prefetches the target chunk on hover/focus, once.
function PrefetchLink({ to, load, children, ...props }) {
  const done = useRef(false);

  const prefetch = () => {
    if (!done.current) {
      load();            // triggers the dynamic import → browser caches the chunk
      done.current = true;
    }
  };

  return (
    <Link to={to} onMouseEnter={prefetch} onFocus={prefetch} {...props}>
      {children}
    </Link>
  );
}

// Usage
<PrefetchLink to="/dashboard" load={() => import('./routes/Dashboard')}>
  Dashboard
</PrefetchLink>

Be considerate about when you prefetch. Respect the user's connection and data-saver preference, and prefer browser idle time so prefetching never competes with what the user is doing right now:

function smartPrefetch(load) {
  const conn = navigator.connection;
  // Skip on data-saver or very slow connections.
  if (conn && (conn.saveData || conn.effectiveType === 'slow-2g')) return;

  if ('requestIdleCallback' in window) {
    requestIdleCallback(() => load());
  } else {
    setTimeout(load, 1000);
  }
}

Measuring the Impact

Splitting is only worthwhile if it moves real metrics. Measure before and after with the right tools:

For a Vite project, add the visualizer to your build:

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [react(), visualizer({ open: true })],
});

Hands-on Exercise

import ProductDetails from './ProductDetails';
import SizeChart from './SizeChart';               // heavy, rarely opened
import ProductReviews from './ProductReviews';     // below the fold
import RecommendedProducts from './RecommendedProducts';
import { useState } from 'react';

function ProductPage() {
  const [showSizeChart, setShowSizeChart] = useState(false);

  return (
    <div>
      <ProductDetails />
      <button onClick={() => setShowSizeChart(true)}>Size Guide</button>
      {showSizeChart && <SizeChart onClose={() => setShowSizeChart(false)} />}
      <ProductReviews />
      <RecommendedProducts />
    </div>
  );
}

import { lazy, Suspense, useState } from 'react';
import ProductDetails from './ProductDetails';   // stays eager
import ErrorBoundary from './ErrorBoundary';

const SizeChart = lazy(() => import('./SizeChart'));
const ProductReviews = lazy(() => import('./ProductReviews'));
const RecommendedProducts = lazy(() => import('./RecommendedProducts'));

function ProductPage() {
  const [showSizeChart, setShowSizeChart] = useState(false);

  return (
    <div>
      <ProductDetails />

      <button onClick={() => setShowSizeChart(true)}>Size Guide</button>
      {showSizeChart && (
        <Suspense fallback={<div>Loading size chart…</div>}>
          <SizeChart onClose={() => setShowSizeChart(false)} />
        </Suspense>
      )}

      <ErrorBoundary fallback={<div>Couldn't load reviews.</div>}>
        <Suspense fallback={<div>Loading reviews…</div>}>
          <ProductReviews />
        </Suspense>
      </ErrorBoundary>

      <Suspense fallback={<div>Loading recommendations…</div>}>
        <RecommendedProducts />
      </Suspense>
    </div>
  );
}

Summary & Quiz

📚 Further Reading

• React docs — lazy
• React docs — Suspense
• web.dev — Reduce JavaScript payloads with code splitting
• React Router — lazy route loading

🚀 What's Next?

You've now covered the three pillars of React performance — memoized rendering, stable references, and lean bundles. Next you'll put the whole module together in the weekend project, building and optimizing an advanced React app end to end.