Code Splitting in React with Lazy and Suspense

In the previous chapter we optimized the execution speed of our components. Today we will optimize the initial load speed.

By default, when we build a React application (using Vite, Webpack or Create React App), the build tool takes all our hundreds of JavaScript files and puts them in a blender to create a single gigantic file (usually called index.js or bundle.js).

If your app has a very heavy “Admin Panel” that only 1% of users use, why force the remaining 99% to download that panel’s code?

The solution is Code Splitting. The idea is to chop that giant file into small pieces and load them only when the user needs them.

React.lazy: Dynamic Import

In standard JavaScript, we are used to static imports at the top of the file:

// ❌ Static Import: Always downloaded, whether used or not.
import PanelAdmin from './pages/PanelAdmin';

React offers us a function called lazy that allows us to define a component that will be imported dynamically.

import { lazy } from 'react';

// ✅ Dynamic Import: Only downloaded when React tries to render it.
const PanelAdmin = lazy(() => import('./pages/PanelAdmin'));

Suspense: Managing the Wait

Since downloading the PanelAdmin-XyZ.js file over the network takes some time (milliseconds or seconds), React asks itself:

What on earth do I show on the screen while the component arrives?

If you try to render a lazy component without anything else, React will throw an error and the app will crash.

We must wrap the lazy component inside a parent component called Suspense.

Suspense accepts a mandatory prop called fallback, which is what React will render while waiting.

import { lazy, Suspense } from 'react';

// 1. Define the lazy component
const HeavyWidget = lazy(() => import('./components/HeavyWidget'));

export default function App() {
  return (
    <div>
      <h1>My Dashboard</h1>
      
      {/* 2. Wrap with Suspense and define the loading state */}
      <Suspense fallback={<div className="spinner">Loading widget...</div>}>
        <HeavyWidget />
      </Suspense>
    </div>
  );
}

Route-based Splitting Pattern

Although you can do lazy loading of a button or a modal, the place where this technique usually makes the most sense is in the Router.

We want each page (/home, /about, /contact) to be a separate “chunk”. This way, the initial load of the website is instant because we only download the Home page.

Let’s refactor our App.jsx:

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

// 1. Transform static imports into lazy ones
const Home = lazy(() => import('./pages/Home'));
const About = lazy(() => import('./pages/About'));
const Dashboard = lazy(() => import('./pages/Dashboard')); // Suppose this one is 2MB

function App() {
  return (
    <div>
      <Navbar />
      
      {/* 2. Wrap ALL routes in a single Suspense */}
      <Suspense fallback={<h3>Loading page... ⏳</h3>}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </Suspense>
    </div>
  );
}

UX: Avoiding the Loading Flash

Code Splitting is great for performance, but it can be bad for User Experience (UX) if we overuse it.

If you put lazy on very small components or ones that load very quickly, the user will see a constant flickering of spinners (Flash of Loading Content).