import { lazy } from 'react';

// Each dynamic import creates an explicit split point
const InventoryDashboard = lazy(() => import('./routes/InventoryDashboard'));
const BillingPortal = lazy(() => import('./routes/BillingPortal'));
const SystemConfiguration = lazy(() => import('./routes/SystemConfiguration'));

import { Suspense, useState } from 'react';
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { RouteFallback } from './components/RouteFallback';

export function AppRouter() {
  return (
    <BrowserRouter>
      <Suspense fallback={<RouteFallback />}>
        <Routes>
          <Route path="/" element={<Navigate to="/inventory" replace />} />
          <Route path="/inventory" element={<InventoryDashboard />} />
          <Route path="/billing" element={<BillingPortal />} />
          <Route path="/config" element={<SystemConfiguration />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

instantly.

import { useCallback, useEffect } from 'react';

interface PreloadRouteProps {
  routePath: string;
  importFactory: () => Promise<{ default: React.ComponentType<any> }>;
}

export function useRoutePreloader({ routePath, importFactory }: PreloadRouteProps) {
  const preload = useCallback(() => {
    // Trigger network fetch; promise is cached by the module system
    importFactory().catch(() => {
      // Silently handle network failures; fallback to on-click fetch
    });
  }, [importFactory]);

  useEffect(() => {
    // Attach to navigation elements via custom attribute or router link wrapper
    const links = document.querySelectorAll(`a[href="${routePath}"]`);
    links.forEach((link) => {
      link.addEventListener('mouseenter', preload);
      link.addEventListener('focus', preload);
    });

    return () => {
      links.forEach((link) => {
        link.removeEventListener('mouseenter', preload);
        link.removeEventListener('focus', preload);
      });
    };
  }, [routePath, preload]);
}

Architecture Rationale

• Why dynamic imports over static? Static imports are resolved at build time and merged into the parent chunk. Dynamic imports create explicit split boundaries that bundlers honor during code generation.
• Why a single Suspense boundary? Wrapping the entire route tree simplifies fallback management and prevents nested loading states. Per-route boundaries are only necessary when fallback UI must be highly contextual.
• Why preloading on hover/focus? Network waterfalls are the primary cause of route transition lag. Preloading shifts the fetch to idle moments, ensuring the chunk is available in the browser cache before React attempts to render the lazy component.

Pitfall Guide

1. Static Import Leakage

Explanation: If a route component is imported statically anywhere in the main bundle's dependency tree, the bundler deduplicates the module and includes it in the initial chunk. The React.lazy() call becomes functionally inert. Fix: Audit the entire import graph. Remove all static references to route components from App.tsx, main.tsx, and shared layout files. Rely exclusively on dynamic imports for route resolution.

2. Entry-Point Eager Loading

Explanation: Top-level imports in the application entry file pull all referenced modules into the initial payload before routing logic executes. This bypasses lazy evaluation entirely. Fix: Keep main.tsx and App.tsx strictly focused on router initialization and global providers. Defer all route component resolution to the routing layer.

3. Missing Suspense Ancestor

Explanation: Rendering a lazy component without a Suspense boundary causes an unhandled Promise rejection. React will crash the render tree and display an error overlay. Fix: Ensure every lazy component is wrapped by a Suspense element. Verify the boundary exists in the component hierarchy, not just in the same file.

4. Vendor Chunk Confusion

Explanation: When multiple routes import the same heavy library (e.g., date-fns, lodash, or a charting library), the bundler extracts it into a shared vendor chunk rather than duplicating it in each route chunk. Developers sometimes interpret this as a failed split. Fix: This is expected bundler behavior. Shared dependencies are correctly isolated to prevent redundancy. Verify splits by checking that route-specific logic resides in separate chunks, even if shared libraries are consolidated.

5. Aggressive Preloading

Explanation: Triggering imports for every possible route on application mount consumes bandwidth, increases memory pressure, and may trigger rate limits on CDN or API gateways. Fix: Scope preloading to visible navigation elements. Use IntersectionObserver for scroll-based preloading or limit hover triggers to top-level menu items. Implement a preloading queue with concurrency limits if necessary.

6. Unreadable Production Chunks

Explanation: Bundlers generate hash-based filenames (e.g., chunk-a1b2c3.js) for cache invalidation. These names obscure stack traces and network logs in production monitoring tools. Fix: Configure explicit chunk naming. Use Webpack magic comments or Vite rollupOptions to assign human-readable identifiers while preserving hash suffixes for caching.

7. Ignoring SSR/SSG Compatibility

Explanation: React.lazy() is a client-side runtime feature. It does not work in server-side rendering contexts where modules must be synchronously available during HTML generation. Fix: For SSR applications, use framework-specific code splitting (e.g., Next.js dynamic imports with ssr: false, or Remix route splitting). Reserve React.lazy() for client-rendered SPAs or hydration-only boundaries.

Production Bundle

Action Checklist

• Audit entry files: Remove all static imports for route components from main.tsx and App.tsx.
• Convert route imports: Replace static imports with lazy(() => import('./path')) for each route boundary.
• Add Suspense boundary: Wrap the route tree with <Suspense fallback={...}> at the router level.
• Configure chunk naming: Apply explicit names to route chunks for production debugging and monitoring.
• Implement preloading: Attach hover/focus listeners to navigation elements to trigger background fetches.
• Verify splits: Run a production build and inspect output files for separate route chunks.
• Test network behavior: Throttle network to 3G/4G and confirm chunks load on demand without blocking initial render.
• Monitor TTI: Track Time to Interactive before and after splitting to quantify performance gains.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small app (< 3 routes, shared deps)	Keep monolithic	Splitting adds complexity with negligible payload reduction	Neutral to negative (build config overhead)
Medium app (5-10 routes, heavy route libs)	Route-level splitting	Isolates heavy UI/charting libs to on-demand chunks	Positive (reduced initial TTI, better caching)
Enterprise app (RBAC, admin vs public)	Role-based chunking	Admin routes never load for public users; security + performance	High positive (bandwidth savings, attack surface reduction)
SSR/Next.js project	Framework dynamic imports	React.lazy() incompatible with server rendering pipelines	Positive (maintains SSR benefits while splitting)

Configuration Template

Vite Configuration (vite.config.ts)

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import visualizer from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    visualizer({
      filename: 'dist/bundle-analysis.html',
      gzipSize: true,
      brotliSize: true,
    }),
  ],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // Explicit vendor separation
          vendor: ['react', 'react-dom', 'react-router-dom'],
          // Route-specific naming for production debugging
          inventory: ['./src/routes/InventoryDashboard.tsx'],
          billing: ['./src/routes/BillingPortal.tsx'],
          config: ['./src/routes/SystemConfiguration.tsx'],
        },
      },
    },
  },
});

Webpack Configuration (webpack.config.js)

module.exports = {
  // ... other config
  optimization: {
    splitChunks: {
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor',
          chunks: 'all',
        },
      },
    },
  },
};

Quick Start Guide

1. Install analysis tooling: Add rollup-plugin-visualizer (Vite) or webpack-bundle-analyzer (Webpack) to inspect chunk boundaries.
2. Convert route imports: Replace static imports in your router file with lazy(() => import('./RouteComponent')).
3. Wrap with Suspense: Add <Suspense fallback={<LoadingSpinner />}> around your <Routes> or route tree.
4. Verify delivery: Run npm run build, open the generated analysis HTML, and confirm route components appear in separate rectangles outside the main bundle.
5. Test navigation: Open DevTools Network tab, filter by JS, and navigate between routes. Confirm new chunk files appear only when routes are accessed.