Code splitting with React.lazy: ship the screen, not the application

Mechanics: a component that suspends until its code arrives

Before you reach for React.lazy, it is worth understanding what the browser is actually doing when it hits a dynamic import — because the fallback flash you will see in development is the observable surface of a network round trip, and knowing that shapes every placement decision that follows.

React.lazy(() => import("./Editor")) returns a component you render like any other. The first time React tries to render it, the loader fires: import() tells the bundler to cut the module (and everything only it imports) into a separate chunk, fetched over the network at that moment. While the promise is pending, the lazy component suspends — the nearest Suspense boundary shows its fallback — and when the module resolves, React renders its default export. The module is fetched and evaluated once; later renders are synchronous.

import { lazy, Suspense } from "react";

const Editor = lazy(() => import("./Editor"));            // needs default export

// Named-export workaround: re-shape the module in the loader
const Chart = lazy(() =>
  import("./charts").then((m) => ({ default: m.RevenueChart }))
);

function ReplyPanel({ open }) {
  return (
    <Suspense fallback={<EditorSkeleton />}>
      {open && <Editor />}
    </Suspense>
  );
}

Two declaration rules prevent self-inflicted bugs. Declare lazy components at module top level — a lazy() created inside a render produces a new component type every render, so React unmounts and remounts the subtree (state loss, re-fetch) each time the parent updates. And lazy resolves the default export only; for named exports, map the module in the loader as above. The deeper point: each lazy boundary is a promise that resolves on network time, which makes placement an architecture decision, not a syntax one.

Where to cut: routes first, components second

The highest-value split is the route: users on one screen get none of the code for the others, the chunk boundary matches a natural loading state (navigation), and modern framework routers do it by default. The Hook’s first fix — separating checkout from the admin’s charting and markdown libraries — was pure route splitting and took the bundle from 612 KB to 240 KB gzipped. As a budget anchor: 300 KB of gzipped JS is roughly 1 MB to parse and execute, which is seconds of CPU on a mid-range phone even after the download finishes — splitting saves parse time, not just bytes.

Component-level splitting earns its keep for things that are heavy and conditional: modals, rich-text editors, chart panels, anything below the fold or behind a click. The test is concrete — open the bundle analyzer and look at the chunk’s actual size. Lazy-loading a 6 KB date picker buys ~nothing and costs a request plus a fallback flash; lazy-loading a 280 KB editor that 4% of sessions open is the whole point. Failure mode — the waterfall: a lazy component whose chunk, once loaded, renders another lazy component creates sequential round trips, because the second request cannot be discovered until the first chunk has arrived and rendered. At 200 ms RTT, three nested boundaries are 600+ ms of pure latency before any rendering work. Keep boundaries siblings (one Suspense, chunks fetched in parallel), not ancestors.

Preloading on intent: spend the latency before the click

A lazy chunk’s latency does not have to start at render time. The dynamic import() is just a function call that warms the module cache — call it early, and by the time React suspends, the promise may already be resolved:

const loadEditor = () => import("./Editor");      // shared loader = shared cache
const Editor = lazy(loadEditor);

<button
  onMouseEnter={loadEditor}                        // intent: ~200-300 ms head start
  onFocus={loadEditor}
  onClick={() => setOpen(true)}
>
  Reply
</button>

Hover-to-click gaps run a few hundred milliseconds — frequently the entire chunk fetch on a decent connection, turning the fallback flash into a non-event. The same idea generalizes: preload route chunks when a link enters the viewport (IntersectionObserver), after first paint for the most-likely next route, or via requestIdleCallback for low-priority warming. The browser-level equivalent is <link rel="modulepreload"> for chunks you know statically. Tradeoff: preloading spends bandwidth on predictions — over-preloading on a data-constrained mobile connection re-creates the monolith one speculative chunk at a time, so tie it to genuine intent signals (hover, focus, viewport) rather than preloading everything.

SSR and the measurement loop

Two operational notes close the topic. Server rendering: on the server there is no “later” — classic React.lazy historically could not be server-rendered, which is why ecosystems grew loadable-components; modern React 18+ streaming SSR plus framework-level route splitting handles this for you, but the hydration constraint remains: the client must load the same chunk before it can hydrate that subtree, so a slow chunk means server-rendered HTML that is visible but inert — wire the fallback so users do not click dead UI. Measurement: code splitting is a bytes game, so verify in bytes. The bundle analyzer (rollup-plugin-visualizer, webpack-bundle-analyzer) shows whether the split actually moved the library out of the entry chunk — a single stray static import of the editor anywhere in the entry graph silently un-splits it, and the analyzer is where you catch that regression. Track the entry chunk size in CI; it is the metric that decays one innocent import at a time.