# Code Splitting with React.lazy and Suspense: A Practical Deep Dive

> A deep dive into code splitting with React.lazy and Suspense — how bundle splitting works, where to split, and how to avoid the pitfalls that slow initial load.

- **Published:** 2026-01-15
- **Author:** Clixo
- **Reading time:** 6 min read
- **Tags:** react, code-splitting, lazy-loading, suspense, bundle-size, performance
- **Canonical URL:** https://clixo.sh/blog/code-splitting-react-lazy-suspense-deep-dive

Your React application ships one large JavaScript bundle and makes every user download code for routes they may never visit. For a typical single-page application, the initial bundle includes authentication pages, admin panels, dashboard views, and reporting screens — all loaded before the user sees anything on screen. Every kilobyte adds latency.

Code splitting is the mechanism that fixes this. `React.lazy` and `Suspense` are React's built-in tools for doing it without a build-configuration overhaul. This guide covers how they work, where to split, and the tradeoffs worth understanding before you implement.

## How Code Splitting with React.lazy Works

JavaScript bundlers — Webpack, Vite, esbuild — have a concept of dynamic imports. Instead of bundling a module into the main chunk at build time, a dynamic import produces a separate chunk file that is downloaded on demand.

`React.lazy` wraps a dynamic import and integrates it with React's rendering lifecycle. When React encounters a lazy component for the first time, it triggers the dynamic import, suspends rendering until the module resolves, and then renders the component.

```js
import { lazy, Suspense } from "react";

const ReportingDashboard = lazy(() => import("./ReportingDashboard"));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <ReportingDashboard />
    </Suspense>
  );
}
```

```mermaid
flowchart LR
  A["User navigates to route"] --> B["React.lazy triggered"]
  B --> C["Dynamic import fires"]
  C --> D["Bundler fetches chunk"]
  D --> E["Suspense shows fallback"]
  E --> F["Module resolves"]
  F --> G["Component renders"]
```

The `Suspense` boundary is required. Without it, React will throw an error when the lazy component suspends. The `fallback` prop renders while the module is loading — typically a skeleton screen or a minimal loading indicator.

## Route-Based Splitting: The Highest-Impact Starting Point

The most impactful place to split is at the route level. Each route in your application maps to a distinct feature — often one that imports its own set of libraries, components, and utilities. Splitting at routes produces separate chunks per page, so a user who lands on the home page downloads only the home page's code.

With React Router:

```js
const SettingsPage = lazy(() => import("./pages/Settings"));
const AdminPanel = lazy(() => import("./pages/Admin"));

function Routes() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <RouterSwitch>
        <Route path="/settings" element={<SettingsPage />} />
        <Route path="/admin" element={<AdminPanel />} />
      </RouterSwitch>
    </Suspense>
  );
}
```

A single `Suspense` boundary around the route switch works for most applications. The fallback renders while any route's chunk is fetching.

## Component-Level Splitting: When Routes Are Not Enough

Some components are large enough to justify splitting even within a route. Good candidates:

- **Modals and drawers** that are conditionally rendered and import heavy libraries.
- **Rich text editors** or code editors that bring in substantial dependencies.
- **Charts and visualization libraries** that are only visible on interaction.
- **Admin-only panels** that the majority of users never see.

The rule of thumb: if a component or its transitive dependencies add more than roughly 30KB to the bundle, consider splitting it.

```js
const RichTextEditor = lazy(() => import("./RichTextEditor"));

function PostForm({ showEditor }) {
  return (
    <div>
      {showEditor && (
        <Suspense fallback={<EditorSkeleton />}>
          <RichTextEditor />
        </Suspense>
      )}
    </div>
  );
}
```

## Analyzing Your Bundle Before Splitting

Code splitting without a bundle analysis is guesswork. Run your bundler's analysis output first to see which modules are largest and which routes they belong to.

For Vite: install `rollup-plugin-visualizer` and run the build with the plugin enabled. For Webpack: use `webpack-bundle-analyzer`. Both produce a treemap showing every module's contribution to bundle size.

Look for:

- Large third-party libraries imported on routes that don't need them.
- Utilities or components that appear in every chunk because they are imported at the top of too many files.
- Icon libraries where the full set is imported rather than individual icons.

The analysis tells you where splits will have real impact. A route that is already 10KB does not need splitting.

## Avoiding the Pitfalls of React.lazy and Suspense

### Waterfall loading

If a parent lazy component imports a child lazy component, they load sequentially — the parent must resolve before React discovers the child and starts its download. Flatten your lazy import hierarchy so sibling chunks load in parallel.

### Missing error boundaries

Network requests fail. A user on a slow connection may fail to fetch a lazy chunk entirely. Without an error boundary above the `Suspense` component, a failed lazy import throws an unhandled error and breaks the entire subtree.

Add an error boundary — React's `ErrorBoundary` pattern or a library like `react-error-boundary` — above any `Suspense` that wraps lazy components in production.

### Over-splitting small components

Splitting a 2KB component creates a network round trip that costs more than the bytes saved. The chunk must be discovered, requested, and parsed. Below a certain size threshold, the latency of the extra HTTP request outweighs the benefit of not bundling the code.

### Named exports and lazy

`React.lazy` only works with default exports. If the component you want to lazy load uses a named export, wrap the import:

```js
const MyComponent = lazy(() =>
  import("./MyComponent").then(mod => ({ default: mod.MyComponent }))
);
```

## Prefetching for Perceived Performance

You can prefetch a lazy chunk before the user navigates to it. When a user hovers over a navigation link, there is typically 100-300ms before they click. That window is enough to start the chunk download.

Trigger the import on hover without rendering the component:

```js
const prefetchReporting = () => import("./pages/Reporting");

return (
  <NavLink to="/reporting" onMouseEnter={prefetchReporting}>
    Reports
  </NavLink>
);
```

This makes navigation feel instant even when the chunk has not been downloaded yet.

## Measuring the Impact

After implementing route-based splitting, measure the initial bundle size using your bundler's stats output. Compare the total bytes downloaded on first load before and after. Then use a tool like Lighthouse or WebPageTest to measure Time to Interactive on a throttled connection.

A typical React application moving from a single 1.5MB bundle to route-based chunks sees a meaningful improvement in TTI on mobile connections. The exact numbers depend on how much code each route pulls in.

If your product team is working on load performance and needs help across the full stack — build configuration, bundle analysis, and architecture decisions — [Clixo builds and ships full-stack React applications](https://clixo.sh/#contact).

---

Clixo · 1141 W Bryn Mawr Ave, Itasca, IL 60143, US · [hello@clixo.sh](mailto:hello@clixo.sh)
[Start a build](https://clixo.sh/#contact) · [All services](https://clixo.sh/services) · [Agent guide (llms.txt)](https://clixo.sh/llms.txt)