Code Splitting with lazy

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Bundle

The JavaScript files a bundler produces from all your modules.

Bundler

A build tool (Vite, webpack, Turbopack) that combines and optimises your modules for the browser.

Code splitting

Breaking the bundle into smaller files that load only when they're needed.

Chunk

One of those smaller files. A dynamic import creates one.

Dynamic import

import("./file") used like a function: it loads a module later and returns a promise.

lazy

A React function that turns a dynamic import into a component that loads on first render.

Fallback

What a Suspense boundary shows while something inside it is still loading.

Preloading

Starting to download code before the user needs it, so it's ready on click.

1. 1

   Make the download fail

   In the first example, change resolve(...) to reject(new Error("Chunk failed")) (and the Promise callback to (resolve, reject) =>). Predict what the page and console show with no error boundary. Then think about where an error boundary with a "Reload" button belongs.

2. 2

   Check the fallback flash

   In the preload example, change the click handler to () => setOpen(true) and log the area at 30 ms and 400 ms after the click. Compare with the transition version.

3. 3

   Preload when idle

   Instead of hover, call loadSettings() from setTimeout(loadSettings, 200) after mount (or requestIdleCallback in a real app). When would that be better than preloading on hover?

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Why bundle size matters. A bundler (Vite, webpack, Turbopack) combines your modules into a few JavaScript files called a bundle. The browser must download, parse and execute that JavaScript before React can render. On a mid-range phone, parsing and running 1 MB of JavaScript can take well over a second, and it blocks the main thread. Shipping less code for the first page is one of the biggest wins for load time.

2. 2

   Code splitting means the bundler puts some modules into separate files, called chunks, loaded on demand. The trigger is a dynamic import: import("./Chart.jsx") is a function-like expression that returns a promise for the module (see /javascript modules). Any bundler that sees it creates a separate chunk for that module and its dependencies.

3. 3

   **lazy** turns a dynamic import into a component: const Chart = lazy(() => import("./Chart.jsx")). The module must have a default export that is a component (or you map it: lazy(() => import("./x").then((m) => ({ default: m.Chart })))). Declare lazy components at the top level of a module, never inside a component: a new lazy each render is a new type and would reload and reset (Topic 16.2). The first time <Chart /> renders, React calls the loader once, and the component suspends until the chunk arrives. After that the module is cached and renders instantly.

4. 4

   Suspense shows the waiting state. A suspended component needs a <Suspense fallback={...}> above it (Topic 14.3). The fallback replaces the boundary's content while the chunk loads. Place boundaries where a loading state makes sense: around a panel, not around the whole app. If the chunk fails to load (offline, a new deployment removed old files), the promise rejects and the nearest error boundary (Topic 14.5) shows; a common fix is offering a reload.

5. 5

   Route-level splitting is the best default: each page becomes its own chunk, because users visit one page at a time. Frameworks do it automatically: Next.js splits per route, and React Router's lazy route property loads a route's module (component, loader, action) on navigation (Topic 13.6). Component-level splitting is for heavy parts that aren't always shown: a chart library, a rich text editor, a map, a modal used rarely.

6. 6

   Preloading removes the wait. Start the import before the user needs it: when they hover or focus a link or button, when the browser is idle, or right after the first page loads. Keep the import promise in a variable so it starts at most once (bundlers also cache modules). Combine it with **startTransition** when showing the lazy component: if the chunk is still loading, React keeps the current screen instead of flashing a fallback, and if it's already loaded, it appears with no fallback at all.

• ↔

  Splitting makes the first load faster but adds requests and a possible wait on first use; preloading trades some bandwidth for a faster later click.

• ↔

  Fine-grained splitting can create waterfalls (a chunk that, once loaded, imports another chunk). Keep heavy dependencies together with the feature that uses them.

• I can explain why bundle size affects load time.

• I can lazy-load a component with a Suspense fallback.

• I can split routes in React Router or rely on Next.js route splitting.

• I can preload a chunk on hover and reveal it in a transition.

• I can handle a failed chunk load with an error boundary.