Code Splitting — React Deep Dive

main bundle vs. lazy chunk — what ships where

A route is split into two files. The non-lazy file (chart.tsx) holds the route config — path, validateSearch, beforeLoad, and the generated types. It is bundled into the main bundle so every <Link to="/chart"> and useSearch() stays type-safe without pulling in the heavy chart code. The lazy file (chart.lazy.tsx) holds the component and loader — it becomes its own chunk, fetched on demand.

piece	bundle	why
`createFileRoute` config (path, validateSearch, beforeLoad)	main bundle (~always)	needed for type-safe `<Link>`, `useSearch`, and matching before the route mounts
`createLazyFileRoute` (component + loader)	lazy chunk (~on demand)	heavy runtime code (charts, editors, maps) — only paid for when the route is visited
route types (inferred)	main bundle	type info is erased at compile time; it never reaches the wire
`<Suspense>` boundary	main bundle	router auto-wraps the lazy route; shows a fallback while the chunk loads

1 · the code-split router you write (edit me)

// createLazyRoute — simulates TanStack Router's createLazyFileRoute.
// The route's COMPONENT + LOADER live in a separate chunk (module-level cache),
// fetched on demand (navigate) or eagerly (prefetch). The route CONFIG (path,
// validateSearch, beforeLoad, types) would live in a NON-lazy file in the main
// bundle — here we represent that as the static `home`/`chart` keys below.
function createLazyRoute(loadFn, label) {
  var cached = null;            // the chunk's exports, once resolved
  var status = 'idle';          // 'idle' | 'loading' | 'loaded'
  var promise = null;
  var subs = [];                // components waiting on this chunk
  function fire() { var s = subs.slice(); subs = []; s.forEach(function (f) { try { f(); } catch (e) {} }); }
  function load() {
    if (promise) return promise;
    status = 'loading';
    promise = loadFn().then(function (Comp) { cached = Comp; status = 'loaded'; fire(); return Comp; });
    return promise;
  }
  return {
    label: label,
    getStatus: function () { return status; },
    prefetch: function () { return load(); },                 // <Link preload="intent"> does this
    // The hook a route component calls. Returns the component, or null (Suspense fallback).
    useComponent: function () {
      var s = React.useState({ Comp: cached, n: 0 });
      function ready() { s[1]({ Comp: cached, n: s[0].n + 1 }); }
      React.useEffect(function () {
        if (cached) { ready(); return; }                       // cache hit → instant (prefetched)
        subs.push(ready);
        load();                                                // cold fetch → chunk download
        return function () { var i = subs.indexOf(ready); if (i >= 0) subs.splice(i, 1); };
      }, []);
      return s[0].Comp || null;
    }
  };
}

// A "heavy" chart that ships in its OWN chunk (~50KB) — resolves after a 600ms
// network round-trip, like a real dynamic import().
var lazyChart = createLazyRoute(function () {
  return new Promise(function (resolve) {
    setTimeout(function () {
      resolve(function ChartComponent(props) {
        return (
          <div data-testid="lazy-chart" className="p-4 bg-[#0d1117] rounded border border-[#30363d]">
            <div className="text-[#61dafb] font-bold mb-1">📊 Chart loaded!</div>
            <div className="text-[#8b949e] text-xs">
              data: {props.data} · fetched on demand · bundle: ~50KB
            </div>
          </div>
        );
      });
    }, 600);
  });
}, 'chart chunk (~50KB)');

// The chart ROUTE component — mounts only when you navigate to /chart.
// (In TanStack this is what chart.lazy.tsx exports; <Suspense> wraps it for you.)
function ChartRoute() {
  var LazyComp = lazyChart.useComponent();
  if (LazyComp) return <LazyComp data="Q1 Revenue" />;
  return (
    <div data-testid="loading" className="p-4 bg-[#0d1117] rounded border border-[#30363d] text-[#8b949e] text-sm flex items-center gap-2">
      <span className="animate-pulse">⏳</span> Loading chart chunk… (~50KB on the wire)
    </div>
  );
}

function CodeSplitDemo() {
  var routeState = React.useState('home');
  var route = routeState[0];
  var setRoute = routeState[1];
  var forceState = React.useReducer(function (x) { return x + 1; }, 0);
  var force = forceState[1];
  var last = React.useRef('idle');

  // Poll the chunk's status so the bundle bar re-renders as idle → loading → loaded.
  React.useEffect(function () {
    var id = setInterval(function () {
      var st = lazyChart.getStatus();
      if (st !== last.current) { last.current = st; force(); }
    }, 60);
    return function () { clearInterval(id); };
  }, []);

  var chunkStatus = lazyChart.getStatus();   // idle | loading | loaded

  var content = route === 'home' ? (
    <div data-testid="home" className="p-4 bg-[#0d1117] rounded border border-[#30363d]">
      <div className="text-[#61dafb] font-bold mb-1">🏠 Home route</div>
      <div className="text-[#8b949e] text-xs">
        Rendered from the MAIN bundle (~200KB). The chart chunk was never fetched.
      </div>
    </div>
  ) : (
    <ChartRoute />
  );

  function navBtnClasses(active) {
    return 'px-3 py-2 rounded text-sm font-bold border ' + (active
      ? 'bg-[#61dafb] text-[#0d1117] border-[#61dafb]'
      : 'bg-transparent text-[#61dafb] border-[#30363d]');
  }

  return (
    <div className="space-y-4">
      {/* navigation — these are the <Link>s; their type info lives in the main bundle */}
      <div className="flex gap-2 flex-wrap">
        <button data-testid="nav-home" className={navBtnClasses(route === 'home')}
          onClick={function () { setRoute('home'); }}>
          🏠 Home <span className="opacity-60 text-xs">/</span> main bundle
        </button>
        <button data-testid="nav-chart" className={navBtnClasses(route === 'chart')}
          onClick={function () { setRoute('chart'); }}>
          📊 Chart <span className="opacity-60 text-xs">/</span> lazy chunk
        </button>
        <button data-testid="prefetch"
          className="px-3 py-2 rounded text-sm font-bold border border-[#f39c12] text-[#f39c12] bg-transparent"
          onClick={function () { lazyChart.prefetch(); force(); }}>
          ⚡ prefetch chart chunk
        </button>
      </div>

      {/* active route content — <Suspense> fallback is the "loading" block */}
      <div>{content}</div>

      {/* bundle-size visualization */}
      <div data-testid="bundle" className="p-4 bg-[#0d1117] rounded border border-[#30363d]">
        <div className="text-xs text-[#8b949e] mb-2 uppercase tracking-wide">bundle size on the wire</div>
        <div className="space-y-2">
          <div className="flex items-center gap-2">
            <span className="text-xs text-[#e6edf3] w-28">main bundle</span>
            <div className="flex-1 h-4 bg-[#161b22] rounded overflow-hidden border border-[#30363d]">
              <div className="h-full bg-[#61dafb]" style={{ width: '100%' }}></div>
            </div>
            <span data-testid="main-size" className="text-xs text-[#61dafb] w-28 text-right">~200KB · always</span>
          </div>
          <div className="flex items-center gap-2">
            <span className="text-xs text-[#e6edf3] w-28">chart chunk</span>
            <div className="flex-1 h-4 bg-[#161b22] rounded overflow-hidden border border-[#30363d]">
              <div data-testid="chunk-bar" className="h-full transition-all duration-300"
                style={{ width: chunkStatus === 'loaded' ? '25%' : '0%', background: '#f39c12' }}></div>
            </div>
            <span data-testid="chunk-size" className="text-xs w-28 text-right"
              style={{ color: chunkStatus === 'idle' ? '#8b949e' : '#f39c12' }}>
              ~50KB · {chunkStatus}
            </span>
          </div>
        </div>
        <div className="text-xs text-[#8b949e] mt-2">
          total downloaded: <span data-testid="total-size" className="text-[#e6edf3] font-bold">
            {chunkStatus === 'loaded' ? '~250KB' : '~200KB'}
          </span> — the chart chunk only ships when you visit <code>/chart</code> or prefetch it.
        </div>
      </div>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<CodeSplitDemo/>);

2 · Babel compiles JSX → element tree

<CodeSplitDemo/> becomes React.createElement(CodeSplitDemo). lazyChart.useComponent() returns the cached component or null (the <Suspense> fallback handles the gap). The status poll re-renders the bundle bar as the chunk transitions idle → loading → loaded.

// (hit "compile & render" to see Babel's output)

3 · live React (the split, proven)

Click Chart to navigate to the lazy route — watch the "Loading chunk…" state, then the chunk resolves (~600ms) and the bar grows to ~250KB. Hit prefetch first and the next navigation is instant (cache hit). The gold-check runs all of this automatically.

chunk: — · gold: home → chart (loading → loaded, ~250KB) → home

intent → pattern

intent	pattern	why
split a heavy route	`createLazyFileRoute('/x')({{component, loader}})` in `x.lazy.tsx`	component + loader ship in their own chunk; fetched only when visited
keep links type-safe	leave `createFileRoute('/x')({{validateSearch, beforeLoad}})` in `x.tsx` (main bundle)	types + matching config are always present; `<Link to="/x">` validates
avoid the loading flash	`<Link preload="intent">` or `router.preloadRoute()`	fetch the chunk on hover/viewport; by click time it's cached → instant
show a fallback while loading	wrap in `<Suspense fallback={{…}}>` (router does this per-route)	lazy component returns a promise; Suspense renders the fallback
split ONLY a component (not a route)	use `React.lazy()` + `<Suspense>` instead	createLazy is route-scoped and also splits the loader — React.lazy cannot