Code Splitting & Lazy Loading in React: The Ultimate Guide

import HeavyDashboard from './components/HeavyDashboard';
import Settings from './components/Settings';
import Analytics from './components/Analytics';

// ALL three components are bundled together
// The browser downloads ALL of them upfront
// Even if the user never visits Settings or Analytics!

function App() {
  return (
    <div>
      <HeavyDashboard />
      <Settings />
      <Analytics />
    </div>
  );
}

import React, { Suspense } from 'react';

// Dynamic imports: these are NOT downloaded upfront!
const HeavyDashboard = React.lazy(() => import('./components/HeavyDashboard'));
const Settings = React.lazy(() => import('./components/Settings'));
const Analytics = React.lazy(() => import('./components/Analytics'));

function App() {
  return (
    <div>
      {/* Suspense shows a fallback while the component loads */}
      <Suspense fallback={<LoadingSpinner />}>
        <HeavyDashboard />
      </Suspense>

      <Suspense fallback={<p>Loading settings...</p>}>
        <Settings />
      </Suspense>

      <Suspense fallback={<SkeletonChart />}>
        <Analytics />
      </Suspense>
    </div>
  );
}

function LoadingSpinner() {
  return (
    <div className="flex items-center justify-center p-8">
      <div className="animate-spin h-8 w-8 border-2
                      border-cyan-400 border-t-transparent
                      rounded-full" />
    </div>
  );
}

import React, { Suspense } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// Each page is lazy loaded, separate chunk per route
const Home = React.lazy(() => import('./pages/Home'));
const Dashboard = React.lazy(() => import('./pages/Dashboard'));
const Settings = React.lazy(() => import('./pages/Settings'));
const Profile = React.lazy(() => import('./pages/Profile'));
const Analytics = React.lazy(() => import('./pages/Analytics'));

// A nice full-page loading skeleton
function PageLoader() {
  return (
    <div style={{
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      minHeight: '60vh',
      flexDirection: 'column',
      gap: '1rem'
    }}>
      <div className="animate-spin h-10 w-10 border-4
                      border-cyan-400 border-t-transparent
                      rounded-full" />
      <p style={{ color: '#8b949e', fontSize: '0.875rem' }}>
        Loading page...
      </p>
    </div>
  );
}

function App() {
  return (
    <BrowserRouter>
      {/* One Suspense wrapper for all routes */}
      <Suspense fallback={<PageLoader />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/settings" element={<Settings />} />
          <Route path="/profile" element={<Profile />} />
          <Route path="/analytics" element={<Analytics />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

app/
├── page.tsx          → chunk: main.js      (loaded on /)
├── dashboard/
│   └── page.tsx      → chunk: dashboard.js (loaded on /dashboard)
├── settings/
│   └── page.tsx      → chunk: settings.js  (loaded on /settings)
└── analytics/
    └── page.tsx      → chunk: analytics.js (loaded on /analytics)
// Next.js automatically code-splits each route!
// No React.lazy() or Suspense needed for routes.

import React, { Suspense, useState } from 'react';

// The heavy modal (with image gallery, reviews, etc.)
// is only loaded when the user clicks "Quick View"
const ProductModal = React.lazy(
  () => import('./components/ProductModal')
);

function ProductPage() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <h1>Our Products</h1>
      <ProductGrid />

      <button onClick={() => setShowModal(true)}>
        Quick View
      </button>

      {/* Modal code is NOT downloaded until clicked */}
      {showModal && (
        <Suspense fallback={<ModalSkeleton />}>
          <ProductModal onClose={() => setShowModal(false)} />
        </Suspense>
      )}
    </div>
  );
}

function ModalSkeleton() {
  return (
    <div style={{
      position: 'fixed', inset: 0,
      background: 'rgba(0,0,0,0.5)',
      display: 'flex', alignItems: 'center',
      justifyContent: 'center'
    }}>
      <div style={{
        width: 500, height: 400,
        borderRadius: '1rem',
        background: '#1a1a2e',
        animation: 'pulse 1.5s infinite'
      }} />
    </div>
  );
}

import React, { Suspense } from 'react';

// Chart.js + react-chartjs-2 is ~200KB
// Only loaded when user visits the analytics tab
const SalesChart = React.lazy(
  () => import('./charts/SalesChart')
);
const RevenueChart = React.lazy(
  () => import('./charts/RevenueChart')
);

function AnalyticsDashboard() {
  const [activeTab, setActiveTab] = useState('overview');

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

      {activeTab === 'overview' && <OverviewCards />}

      {activeTab === 'sales' && (
        <Suspense fallback={<ChartSkeleton />}>
          <SalesChart />
        </Suspense>
      )}

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

function ChartSkeleton() {
  return (
    <div style={{
      height: 300, borderRadius: '1rem',
      background: 'linear-gradient(90deg, #1a1a2e 25%, #2a2a4e 50%, #1a1a2e 75%)',
      backgroundSize: '200% 100%',
      animation: 'shimmer 1.5s infinite',
    }} />
  );
}

// ❌ This WON'T work — React.lazy needs a default export
const MyChart = React.lazy(() => import('./Charts'));
// Error: Charts doesn't have a default export!

// ✅ Fix 1: wrap the named export as default in .then()
const LazyChart = React.lazy(() =>
  import('./Charts').then(module => ({
    default: module.MyChart  // Wrap named export as default
  }))
);

// ✅ Fix 2: create a barrel file that re-exports as default
// Charts/index.ts
export { MyChart as default } from './MyChart';

// Now you can lazy import normally
const LazyChart2 = React.lazy(() => import('./Charts'));

import React from 'react';

/**
 * Helper to lazy-load named exports
 * Usage: const { MyComponent } = lazyImport(() => import('./file'), 'MyComponent')
 */
export function lazyImport<
  T extends React.ComponentType<any>,
  K extends string
>(factory: () => Promise<Record<K, T>>, name: K) {
  return {
    [name]: React.lazy(() =>
      factory().then(module => ({
        default: module[name]
      }))
    )
  } as Record<K, React.LazyExoticComponent<T>>;
}

// Usage
const { UserProfile } = lazyImport(
  () => import('./components/Users'),
  'UserProfile'
);

const { SettingsPanel } = lazyImport(
  () => import('./components/Settings'),
  'SettingsPanel'
);

import React, { Component } from 'react';

interface Props {
  children: React.ReactNode;
  fallback?: React.ReactNode;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || (
        <div style={{
          padding: '2rem',
          textAlign: 'center',
          borderRadius: '1rem',
          background: 'rgba(239,68,68,0.1)',
          border: '1px solid rgba(239,68,68,0.2)'
        }}>
          <h3>Something went wrong</h3>
          <p>Failed to load this section.</p>
          <button onClick={() => window.location.reload()}>
            Try Again
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

import React, { Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const Dashboard = React.lazy(() => import('./pages/Dashboard'));

function App() {
  return (
    // Error Boundary catches chunk-load failures
    <ErrorBoundary fallback={<ChunkErrorFallback />}>
      {/* Suspense handles the loading state */}
      <Suspense fallback={<LoadingSpinner />}>
        <Dashboard />
      </Suspense>
    </ErrorBoundary>
  );
}

function ChunkErrorFallback() {
  return (
    <div style={{ textAlign: 'center', padding: '4rem' }}>
      <h2>Oops! Failed to load</h2>
      <p>Check your internet connection and try again.</p>
      <button
        onClick={() => window.location.reload()}
        style={{
          padding: '0.75rem 2rem',
          borderRadius: '9999px',
          background: 'linear-gradient(135deg, #22d3ee, #818cf8)',
          border: 'none',
          color: '#0a0e14',
          fontWeight: 700,
          cursor: 'pointer'
        }}
      >
        Reload Page
      </button>
    </div>
  );
}

// Store the lazy component reference
const Dashboard = React.lazy(() => import('./pages/Dashboard'));

// Preload function: call import() again to trigger download
function preloadDashboard() {
  import('./pages/Dashboard');
  // Calling import() twice won't download twice — the module
  // system returns the same Promise, and the browser HTTP cache
  // prevents duplicate network requests.
}

function Navigation() {
  return (
    <nav>
      <Link to="/">Home</Link>

      {/* Start downloading when user HOVERS over the link */}
      <Link
        to="/dashboard"
        onMouseEnter={preloadDashboard}  // Preload!
        onFocus={preloadDashboard}        // Accessibility
      >
        Dashboard
      </Link>
    </nav>
  );
}

import { useEffect } from 'react';

// Lazy components
const Dashboard = React.lazy(() => import('./pages/Dashboard'));
const Settings = React.lazy(() => import('./pages/Settings'));

function App() {
  useEffect(() => {
    // After the main page loads and the user is idle,
    // start preloading the most likely next pages
    const timer = setTimeout(() => {
      import('./pages/Dashboard');
      import('./pages/Settings');
    }, 3000); // Wait 3 seconds after mount

    return () => clearTimeout(timer);
  }, []);

  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  );
}

# Analyze your bundle with webpack-bundle-analyzer
npm install --save-dev webpack-bundle-analyzer

# For Next.js, use @next/bundle-analyzer
npm install @next/bundle-analyzer

# For Vite, use rollup-plugin-visualizer
npm install --save-dev rollup-plugin-visualizer

# Then run your build and inspect the output:
npm run build
# Look at the chunk sizes in the build output!

// Next.js bundle analyzer setup
import withBundleAnalyzer from '@next/bundle-analyzer';

const config = withBundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})({
  // your Next.js config
});

export default config;

// Run with: ANALYZE=true npm run build

Wrapping Up

Code splitting and lazy loading aren't just "nice to have." They're essential for any React app that cares about user experience and SEO. Here's your action plan:

1. Start with route-based splitting (biggest impact, lowest effort)
2. Lazy load heavy components: modals, charts, editors, maps
3. Add Suspense + Error Boundaries everywhere you lazy load
4. Preload on hover for critical navigation paths
5. Measure with Lighthouse & bundle analyzer. Trust data, not gut feeling
6. Don't over-split. Tiny components don't need their own chunk

Remember the pizza delivery analogy? Stop shipping the entire restaurant. Ship just the pizza. Your users (and their slow 3G connections) will thank you.