Route-Based Code Splitting with React lazy0%
Component-Level Lazy Loading with Suspense

Route-Based Code Splitting with React lazy

Beginner12 min read•Updated: Jul 11, 2026
Study MaterialsCheatsheet

Route-Based Code Splitting with React lazy

In monolithic single-page applications (SPAs), bundling an entire codebase into a single monolithic JavaScript payload degrades Initial Page Load performance, causing high First Contentful Paint (FCP) and Time to Interactive (TTI) scores. Route-based code splitting dynamically segments your JavaScript application into separate chunks loaded strictly on demand when a user navigates to a corresponding URL.

1. The Need for Route-Based Code Splitting

When Webpack, Vite, or Rollup bundles your application without splitting, every component, charting library, date-math utility, and admin module is sent to the client browser on the very first HTTP request. Even if the user only visits a simple landing page, they pay the bandwidth, decompression, and parsing cost for 50 other internal dashboards.

Output
Monolithic Bundle:
[ Landing Page | Analytics Engine | D3 Charts | User Settings | Billing & Invoicing | Admin Portal ]
Size: 3.8 MB (Loaded all at once on initial visit)
 
Route-Split Bundles:
[ Core Runtime + Shared Vendors ] (220 KB, initial load)
├── Navigates to /analytics ──> [ analytics.chunk.js ] (450 KB)
├── Navigates to /billing ──> [ billing.chunk.js ] (180 KB)
└── Navigates to /admin ──> [ admin.chunk.js ] (320 KB)

2. Dynamic Imports and React.lazy()

React.lazy() lets you render a dynamic import as a regular React component. It takes a function that must call a dynamic import(), which returns a Promise that resolves to a module with a default export containing a React component.

TSX
import React, { Suspense, lazy } from "react";
import { BrowserRouter, Routes, Route, Link } from "react-router-dom";
 
// Lazy-loaded route components
const DashboardPage = lazy(() => import("./pages/DashboardPage"));
const AnalyticsPage = lazy(() => import("./pages/AnalyticsPage"));
const SettingsPage = lazy(() => import("./pages/SettingsPage"));
 
// Suspense fallback skeleton
function PageLoadingSkeleton() {
return (
<div className="flex h-screen items-center justify-center bg-slate-900 text-white">
<div className="flex flex-col items-center gap-3">
<div className="h-10 w-10 animate-spin rounded-full border-4 border-cyan-500 border-t-transparent" />
<p className="text-sm font-medium text-slate-400">Loading module chunk...</p>
</div>
</div>
);
}
 
export function AppRouter() {
return (
<BrowserRouter>
<nav className="flex gap-4 border-b border-slate-800 bg-slate-950 p-4 text-cyan-400">
<Link to="/">Dashboard</Link>
<Link to="/analytics">Analytics</Link>
<Link to="/settings">Settings</Link>
</nav>
 
{/* Suspense boundary wrapping lazy route rendering */}
<Suspense fallback={<PageLoadingSkeleton />}>
<Routes>
<Route path="/" element={<DashboardPage />} />
<Route path="/analytics" element={<AnalyticsPage />} />
<Route path="/settings" element={<SettingsPage />} />
</Routes>
</Suspense>
</BrowserRouter>
);
}

3. Handling Named Exports with React.lazy()

React.lazy requires that the dynamically imported module has a default export. If a library or design system uses named exports exclusively, you must intermediate the Promise resolution:

TSX
// Importing named export { AdminAnalytics } from module
const AdminAnalytics = lazy(() =>
import("./modules/AdminDashboard").then((module) => ({
default: module.AdminAnalytics,
}))
);

4. Chunk Naming and Build Configurations

In Vite (using Rollup) or Webpack, configure manualChunks or magic comments to generate predictable chunk names for optimal cache invalidation.

TypeScript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
plugins: [react()],
build: {
rollupOptions: {
output: {
manualChunks(id) {
if (id.includes("node_modules")) {
if (id.includes("recharts") || id.includes("d3")) {
return "vendor-charts";
}
if (id.includes("react-router-dom")) {
return "vendor-router";
}
return "vendor-core";
}
},
},
},
},
});

5. Summary Best Practices

  1. 1
    Top-Level Route Splitting: Split at top-level navigation routes first; this delivers the highest return on investment for FCP reduction.
  2. 2
    Granular Suspense Boundaries: Avoid wrapping the entire application in a single Suspense fallback that hides navigation chrome; wrap individual route views inside a stable layout.
  3. 3
    Chunk Prefetching: Prefetch chunks on link hover or intent to reduce navigation latency before the click occurs.
Interactive Quiz

Practice Quiz

Question 1
What contract must the function passed to React.lazy() satisfy?
Question 2
What happens if a React.lazy component renders without an ancestor Suspense component?
Question 3
How can you load a named export { SettingsModal } using React.lazy()?
Question 4
Why is route-based code splitting typically prioritized over fine-grained component splitting?
Question 5
What is the primary benefit of configuring manualChunks in Rollup/Vite for route-split apps?
Next Lesson

Component-Level Lazy Loading with Suspense

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous LessonNext Lesson
Next.js App Router and Server-First ParadigmsComponent-Level Lazy Loading with Suspense

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

PreviousNext
PrevNext