Code Splitting and Lazy Loading — React.lazy, Suspense, and Dynamic Imports

---

Hey everyone, Richa here! 👋

Day 22. And today we talk about one of the most impactful performance wins available in any React app — and one of the most underused.

Code splitting.

Here's the thing about JavaScript bundles. When you build a React app, by default everything gets bundled into one (or a few) large JS files. The browser has to download, parse, and execute all of that before the user sees anything interactive.

Your settings page. Your admin dashboard. Your rarely-visited "about" page. All downloaded upfront. Even if the user is only visiting the homepage.

Code splitting lets you break that bundle into smaller chunks — and load them only when they're needed.

The problem — one giant bundle

Without code splitting:

main.bundle.js  →  2.4MB
                   ├── Login page
                   ├── Dashboard (complex, lots of charts)
                   ├── Settings
                   ├── Admin panel
                   ├── Reports page (rarely visited)
                   └── ... everything else

User visits the login page. Browser downloads 2.4MB of JavaScript. Most of it is code for pages they haven't visited yet and might never visit.

With code splitting:

main.bundle.js     →  180KB  (shared code, router, auth)
login.chunk.js     →  45KB   (loaded when user hits /login)
dashboard.chunk.js →  380KB  (loaded when user navigates to /dashboard)
admin.chunk.js     →  220KB  (loaded when admin navigates to /admin)
reports.chunk.js   →  160KB  (loaded only if user visits /reports)

User visits the login page. Browser downloads 180KB + 45KB = 225KB. Everything else loads on demand as the user navigates.

---

React.lazy — the built-in solution

React.lazy lets you import a component dynamically. The component's code is loaded only when it's first rendered.

import { lazy, Suspense } from 'react';

// ❌ Eager import — Dashboard code is in the main bundle regardless
import { DashboardPage } from './pages/DashboardPage';

// ✅ Lazy import — Dashboard code loads only when this component is rendered
const DashboardPage = lazy(() => import('./pages/DashboardPage'));

React.lazy always works with Suspense. Suspense shows a fallback while the chunk is loading:

import { lazy, Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { Spinner } from '@shared/components';

// Lazy import every page
const LoginPage      = lazy(() => import('./pages/LoginPage'));
const DashboardPage  = lazy(() => import('./pages/DashboardPage'));
const ProductsPage   = lazy(() => import('./pages/ProductsPage'));
const AdminPage      = lazy(() => import('./pages/AdminPage'));
const ReportsPage    = lazy(() => import('./pages/ReportsPage'));

export function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<Spinner fullPage />}>
        <Routes>
          <Route path="/login"      element={<LoginPage />} />
          <Route path="/dashboard"  element={<DashboardPage />} />
          <Route path="/products"   element={<ProductsPage />} />
          <Route path="/admin"      element={<AdminPage />} />
          <Route path="/reports"    element={<ReportsPage />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

Now each page is its own chunk. Navigating to /dashboard for the first time triggers a network request for DashboardPage's chunk. Suspense shows the spinner while it loads — then renders the page.

💡 Route-level splitting is the highest-impact change you can make. Every page becomes its own chunk. Users only download code for pages they visit.

---

Granular splitting — lazy loading heavy components

Not just pages. Any heavy component that isn't needed on first render is a splitting candidate.

// A charting library — very heavy, only needed on the reports page
const RevenueChart = lazy(() => import('./components/RevenueChart'));
const UserGrowthChart = lazy(() => import('./components/UserGrowthChart'));

function ReportsPage() {
  const [activeTab, setActiveTab] = useState<'revenue' | 'users'>('revenue');

  return (
    <div>
      <TabBar active={activeTab} onChange={setActiveTab} />

      <Suspense fallback={<ChartSkeleton />}>
        {activeTab === 'revenue' && <RevenueChart />}
        {activeTab === 'users' && <UserGrowthChart />}
      </Suspense>
    </div>
  );
}

The charting library (Recharts, Chart.js, etc.) can be 200–400KB. If it's only on the reports page — there's no reason it's in the main bundle.

---

Named exports and lazy — the gotcha

React.lazy only works with default exports. If your component uses a named export, you need a wrapper:

// ❌ Won't work — lazy requires a default export
const { ProductList } = lazy(() => import('./components/ProductList'));

// ✅ Fix option 1 — add default export to the file
// ProductList.tsx
export default function ProductList() { /* ... */ }

// ✅ Fix option 2 — re-export as default in the lazy import
const ProductList = lazy(() =>
  import('./components/ProductList').then(module => ({
    default: module.ProductList,
  }))
);

The .then() pattern is useful when you can't modify the source file (third-party components, existing code).

---

Suspense boundaries — where to put them

Suspense can be nested. Use multiple boundaries to control what shows a spinner and what doesn't.

// One Suspense at the top — entire page goes blank while chunk loads
function App() {
  return (
    <Suspense fallback={<FullPageSpinner />}>
      <Routes>...</Routes>
    </Suspense>
  );
}

// Nested Suspense — shell renders immediately, content streams in
function DashboardPage() {
  return (
    <DashboardShell>           {/* renders immediately — no lazy */}
      <Suspense fallback={<StatsSkeleton />}>
        <StatsPanel />         {/* lazy — loads its own chunk */}
      </Suspense>

      <Suspense fallback={<ChartSkeleton />}>
        <RevenueChart />       {/* lazy — loads separately */}
      </Suspense>

      <Suspense fallback={<TableSkeleton />}>
        <RecentOrdersTable />  {/* lazy — loads separately */}
      </Suspense>
    </DashboardShell>
  );
}

With nested boundaries, the page shell appears instantly. Each section loads independently and replaces its skeleton when ready. Users see content progressively — much better experience than waiting for everything at once.

---

Preloading — loading chunks before they're needed

The downside of lazy loading: there's a delay when the user first navigates to a lazy route. Small — usually 100–300ms — but perceptible.

You can preload chunks before the user actually navigates — triggered by hover or focus:

// Preload on hover — chunk loads while user is moving their mouse
const DashboardPage = lazy(() => import('./pages/DashboardPage'));

// Create a preload function
function preloadDashboard() {
  import('./pages/DashboardPage'); // triggers the network request
}

function Navbar() {
  return (
    <nav>
      <Link
        to="/dashboard"
        onMouseEnter={preloadDashboard}  // preload on hover
        onFocus={preloadDashboard}       // preload on keyboard focus
      >
        Dashboard
      </Link>
    </nav>
  );
}

By the time the user clicks, the chunk is already loaded. Zero perceived delay.

---

Dynamic imports for non-component code

React.lazy is for components. But you can dynamically import anything — libraries, utilities, large data.

// Only load the PDF generation library when the user clicks "Export"
async function handleExportPDF() {
  const { generatePDF } = await import('./utils/pdfGenerator');
  await generatePDF(reportData);
}

// Only load a large locale file when needed
async function loadLocale(locale: string) {
  const { messages } = await import(`./locales/${locale}.json`);
  return messages;
}

// Only load a heavy validation library when the form is submitted
async function handleFormSubmit(data: FormData) {
  const { validate } = await import('heavy-validation-library');
  const errors = await validate(data);
  if (errors.length > 0) return setErrors(errors);
  await submitForm(data);
}

This pattern is especially useful for:

• Export features (PDF, Excel) — heavy libraries only when export is triggered
• Rich text editors — load only when user clicks "edit"
• Maps — load the mapping library only when the map component is rendered
• Large datasets — load only when the user requests them

---

Measuring — how to know if it's working

After adding code splitting, verify it's actually working:

In the browser:

1. Open DevTools → Network tab
2. Filter by JS
3. Navigate to different routes
4. Watch new chunk files download as you navigate

With Vite's bundle analyser:

npm install --save-dev rollup-plugin-visualizer

// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    visualizer({ open: true }), // opens a visual bundle map after build
  ],
});

npm run build

The visualiser shows you exactly what's in each chunk. If you see chart.js in your main bundle when it should only be on the reports page — you have a missed split.

---

Common mistakes

Mistake 1 — Splitting too granularly

// ❌ Splitting a tiny component — chunk overhead costs more than it saves
const MySmallButton = lazy(() => import('./SmallButton')); // 2KB component

Network overhead for a chunk request is ~20ms minimum. For tiny components, the loading delay is worse than just including them in the main bundle. Split components that are > 30KB or that are heavy dependencies (chart libraries, editors, maps).

Mistake 2 — No loading fallback

// ❌ No fallback — user sees nothing while chunk loads
<Suspense>
  <HeavyComponent />
</Suspense>

// ✅ Always provide a meaningful fallback
<Suspense fallback={<Skeleton height={400} />}>
  <HeavyComponent />
</Suspense>

Mistake 3 — Lazy importing inside a component

// ❌ This creates a new lazy component on every render — loses the cache
function MyPage() {
  const Chart = lazy(() => import('./Chart')); // wrong — inside component
  return <Chart />;
}

// ✅ Always define lazy imports at module level
const Chart = lazy(() => import('./Chart')); // correct — outside component

function MyPage() {
  return <Chart />;
}

---

Today's takeaway

Code splitting is one of the highest-ROI performance improvements you can make. Route-level splitting alone can cut your initial bundle by 60–80%.

The pattern is simple:

1. lazy() for the import
2. Suspense with a meaningful fallback
3. Preload on hover for zero perceived delay

Start with route-level splitting. Then identify heavy components (chart libraries, rich text editors, maps) and split those next. Use the bundle visualiser to find what's still in the main bundle that shouldn't be.

See you tomorrow for Day 23 — List virtualisation: rendering 10,000 rows without killing the browser.

---

← Day 21 — Rendering Patterns → Day 23 — List Virtualisation

---

Part of the React System Design Series — 40 days, one topic per day.