React lazy loading patterns

{ fallback: ReactNode; onError?: (error: Error, info: ErrorInfo) => void; }

interface ErrorBoundaryState { hasError: boolean; retryCount: number; }

class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> { state: ErrorBoundaryState = { hasError: false, retryCount: 0 };

static getDerivedStateFromError() { return { hasError: true, retryCount: 0 }; }

componentDidCatch(error: Error, info: ErrorInfo) { this.props.onError?.(error, info); }

handleRetry = () => { this.setState((prev) => ({ hasError: false, retryCount: prev.retryCount + 1 })); };

render() { if (this.state.hasError) { // In production, implement max retry logic or fallback to offline UI return ( <div className="error-fallback"> <p>Failed to load component.</p> <button onClick={this.handleRetry}>Retry</button> </div> ); } return this.props.children; } }

export const LazyRoute = <P extends object>( importFn: () => Promise<{ default: ComponentType<P> }>, fallback: ReactNode, maxRetries = 3 ) => { const LazyComponent = React.lazy(importFn);

return (props: P) => ( <ErrorBoundary fallback={fallback} onError={(e) => console.error('Chunk load error:', e)}> <Suspense fallback={fallback}> <LazyComponent {...props} /> </Suspense> </ErrorBoundary> ); };

**Usage:**
```tsx
const Dashboard = LazyRoute(
  () => import('./pages/Dashboard'),
  <DashboardSkeleton />
);

2. Prefetching on Interaction

Prefetching should be triggered by high-probability signals. The most effective pattern is prefetching on hover for navigation elements.

// hooks/usePrefetch.ts
import { useEffect, useRef } from 'react';

export const usePrefetch = (importFn: () => Promise<unknown>) => {
  const prefetched = useRef(false);

  const triggerPrefetch = () => {
    if (!prefetched.current) {
      importFn();
      prefetched.current = true;
    }
  };

  return triggerPrefetch;
};

// Usage in Navigation
const NavLink = ({ to, children }: { to: string; children: React.ReactNode }) => {
  const prefetchDashboard = usePrefetch(() => import('./pages/Dashboard'));
  
  return (
    <a 
      href={to} 
      onMouseEnter={prefetchDashboard}
      onTouchStart={prefetchDashboard}
    >
      {children}
    </a>
  );
};

3. Intersection Observer for Heavy Components

For components below the fold or inside modals, use IntersectionObserver to prefetch when the component enters the viewport, ensuring the chunk is ready by the time interaction occurs.

// components/LazyObserver.tsx
import { useEffect, useRef, useState } from 'react';
import { Suspense, ComponentType } from 'react';

export const LazyObserver = <P extends object>({
  importFn,
  fallback,
  ...props
}: { 
  importFn: () => Promise<{ default: ComponentType<P> }>; 
  fallback: React.ReactNode;
} & P) => {
  const ref = useRef<HTMLDivElement>(null);
  const [Component, setComponent] = useState<ComponentType<P> | null>(null);

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          importFn().then((mod) => setComponent(() => mod.default));
          observer.disconnect();
        }
      },
      { rootMargin: '200px' } // Prefetch 200px before visibility
    );

    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, [importFn]);

  return (
    <div ref={ref}>
      {Component ? (
        <Suspense fallback={fallback}>
          <Component {...props} />
        </Suspense>
      ) : (
        fallback
      )}
    </div>
  );
};

4. Architecture Decisions

• Chunk Grouping: Use webpackChunkName or Vite manual chunks to group related routes. Splitting every component creates a "chunk explosion," increasing HTTP request overhead. Group by domain feature.
• Critical Path Exclusion: Never lazy load the hero section or primary navigation. These must be in the initial bundle to satisfy Core Web Vitals (LCP).
• SSR Consideration: React.lazy is not compatible with SSR. For Next.js or Remix, use framework-native dynamic imports (next/dynamic or Remix.lazy). The patterns above apply to CSR applications or hydration-free islands.

Pitfall Guide

1. Chunk Explosion:

   • Mistake: Applying React.lazy to every component.
   • Impact: Increases HTTP request count, causing network waterfalls. Browser limits concurrent connections; too many chunks delay rendering.
   • Fix: Lazy load only routes and heavy components (>50KB gzipped). Group related components into shared chunks.

2. Missing Suspense Fallback:

   • Mistake: Omitting <Suspense> or providing no fallback.
   • Impact: UI flickers or displays empty space during chunk load. Users perceive the app as broken.
   • Fix: Always provide a skeleton or loading indicator that matches the layout of the lazy component to prevent CLS (Cumulative Layout Shift).

3. Ignoring Chunk Load Failures:

   • Mistake: Assuming chunks always load. Network interruptions or deployment rollouts can cause 404s for old chunk hashes.
   • Impact: Unhandled promise rejections crash the app.
   • Fix: Implement Error Boundaries with retry logic. Detect 404 chunk errors and trigger a soft refresh or fallback UI.

4. Prefetching Waste:

   • Mistake: Prefetching all routes or heavy assets on page load.
   • Impact: Wastes user bandwidth and battery, especially on mobile. Increases contention with critical resources.
   • Fix: Prefetch only based on intent (hover, scroll proximity) or high-probability user flows. Use rel="prefetch" for static assets sparingly.

5. State Loss on Re-render:

   • Mistake: Placing Suspense boundaries inside components that hold state.
   • Impact: When a lazy component re-renders due to a dependency change, Suspense may unmount and remount the component, losing local state.
   • Fix: Lift state out of lazy components or ensure dependencies are stable. Use React.memo to prevent unnecessary re-renders.

6. Lazy Loading Critical Paths:

   • Mistake: Lazy loading the LCP element or primary navigation.
   • Impact: Delays LCP, hurting SEO and perceived speed.
   • Fix: Audit the critical rendering path. Keep LCP and above-the-fold content in the initial bundle.

7. Inconsistent Chunk Naming:

   • Mistake: Relying on auto-generated chunk IDs.
   • Impact: Debugging performance issues is difficult; cache invalidation becomes unpredictable.
   • Fix: Use explicit naming conventions (e.g., /* webpackChunkName: "auth-login" */) to identify chunks in network panels and bundle analyzers.

Production Bundle

Action Checklist

• Audit Bundle: Run webpack-bundle-analyzer or rollup-plugin-visualizer to identify heavy dependencies and split points.
• Implement Route Splitting: Convert all route-level imports to React.lazy with Suspense and ErrorBoundary.
• Add Prefetch Hooks: Implement usePrefetch on navigation elements and high-probability interactive triggers.
• Configure Manual Chunks: Group vendor libraries (React, Router, UI Kit) and feature-specific modules using build tool configuration.
• Test Throttling: Validate performance on 3G throttling and Moto G4/Low-end device profiles in Chrome DevTools.
• Verify Error Handling: Simulate chunk load failures by blocking network requests for specific chunks; ensure fallback UI renders.
• Monitor CLS: Ensure lazy loading skeletons maintain layout dimensions to prevent layout shifts.
• Review SSR Compatibility: If using SSR, replace React.lazy with framework-specific dynamic imports.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Marketing / SEO Site	Route-based only	Maximizes TTI; SEO crawlers need content immediately. Prefetching adds complexity with low ROI.	Low
SaaS Dashboard	Route + Prefetch on Hover	Users navigate frequently; prefetching eliminates nav latency. High engagement justifies bandwidth usage.	Medium
Low-End Mobile Focus	Aggressive Splitting + Lazy Observer	Memory constraints require minimal initial footprint. Observer ensures chunks load only when needed.	Low
Enterprise Internal Tool	Hybrid with Manual Chunks	Users have stable connections; focus on developer experience and chunk organization.	Medium
Content Heavy App	Component-level + Intersection	Images and heavy widgets dominate payload. Lazy loading components prevents blocking render.	Medium

Configuration Template

Vite Configuration for Manual Chunks:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // Group core dependencies
          'vendor-react': ['react', 'react-dom'],
          'vendor-router': ['react-router-dom'],
          'vendor-ui': ['@mui/material', '@emotion/react', '@emotion/styled'],
          
          // Group feature modules
          'feature-auth': ['./src/features/auth'],
          'feature-dashboard': ['./src/features/dashboard'],
          'feature-reports': ['./src/features/reports'],
        },
      },
    },
  },
});

Webpack Configuration (Legacy):

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
        },
        common: {
          minChunks: 2,
          priority: -10,
          reuseExistingChunk: true,
        },
      },
    },
  },
};

Quick Start Guide

1. Initialize Lazy Wrapper: Create src/utils/LazyRoute.tsx with the ErrorBoundary and Suspense wrapper pattern from the Core Solution.

2. Convert Routes: Replace static imports in your router configuration:

   // Before
   import Settings from './pages/Settings';
   // After
   const Settings = LazyRoute(() => import('./pages/Settings'), <LoadingSpinner />);
   

3. Add Prefetch to Nav: Implement the usePrefetch hook on your primary navigation links to preload destination chunks on hover.

4. Verify Build: Run npm run build and inspect the output directory. Confirm multiple chunk files are generated and chunk names are descriptive.

5. Test Performance: Open Chrome DevTools → Network tab → Throttle to "Slow 3G". Navigate through the app. Verify that initial load is fast and subsequent navigations trigger chunk downloads without UI crashes.

This architecture provides a scalable, resilient foundation for React lazy loading. By balancing initial payload reduction with intelligent prefetching and robust error handling, you achieve optimal performance across diverse user environments while maintaining development velocity.