Navigation & Preloading — React Deep Dive

fetch on click vs. fetch on intent

A normal <Link> is "click then fetch" — the user clicks, the router runs the route's beforeLoad → loader, downloads the JS chunk, THEN paints. Preloading inverts the timeline: the router starts that work the instant a link signals intent (hover / tap / enters viewport). By the time the click lands, the result is already in the cache and the navigation is INSTANT. Same data, same loaders — just moved earlier.

piece	role	default
`preload`	trigger policy on `<Link>`: `false` \| `'intent'` \| `'viewport'`	`false` (opt-in)
`'intent'`	preload on `mouseenter` (desktop hover) + `pointerdown`/`touchstart` (mobile tap), after `preloadDelay` ms	delay `0`ms
`'viewport'`	preload via `IntersectionObserver` the moment the link scrolls into view	eager — all visible links
`staleTime`	how long a preloaded entry is considered fresh (no refetch on navigate)	`30_000`ms (navigations: `0`)
`gcTime`	how long an unused preloaded entry survives in memory before garbage collection	`300_000`ms (5min)

Deduplication is free: two links to the same route share one in-flight preload; if a preload is mid-flight when the click arrives, the result is reused — no double fetch.

1 · the preloading pipeline (edit me)

// ---- Route table (in real TanStack these come from the route tree) ----
var ROUTES = [
  { path: '/',         label: 'Home',     hue: '#61dafb' },
  { path: '/users',    label: 'Users',    hue: '#2ecc71' },
  { path: '/settings', label: 'Settings', hue: '#f39c12' },
  { path: '/posts',    label: 'Posts',    hue: '#9b59b6' }
];
var STRATEGIES = ['none', 'hover', 'tap', 'viewport'];

// ---- Module-scoped preload cache (dedup happens here) ----
// Each route path is the dedup key. 'loading' = in-flight, 'cached' = resolved.
var cache = {};
var logSeq = 0;
var FETCH_MS = 400;   // simulate the route's loader/beforeLoad latency

function NavigationDemo() {
  var stratState = React.useState('hover');
  var strategy = stratState[0];
  var setStrategy = stratState[1];

  var logState = React.useState([]);
  var logs = logState[0];
  var setLogs = logState[1];

  var cacheSnapState = React.useState({});
  var cacheSnap = cacheSnapState[0];
  var setCacheSnap = cacheSnapState[1];

  var curRouteState = React.useState('/');
  var currentRoute = curRouteState[0];
  var setCurrentRoute = curRouteState[1];

  var navStatusState = React.useState(null);
  var navStatus = navStatusState[0];
  var setNavStatus = navStatusState[1];

  // ---- push a log row + snapshot the cache so the UI re-renders ----
  function pushLog(entry) {
    entry.id = ++logSeq;
    setLogs(function (prev) { return prev.concat([entry]); });
  }
  function sync() { setCacheSnap(Object.assign({}, cache)); }

  // ---- the preload fn: dedup → start → async resolve ----
  function startPreload(path, intent) {
    // DEDUP: already loading or cached? → reuse, no new fetch
    if (cache[path]) {
      pushLog({ route: path, action: 'CACHE HIT', intent: intent });
      return;
    }
    cache[path] = 'loading';
    pushLog({ route: path, action: 'PRELOAD START', intent: intent });
    sync();
    setTimeout(function () {
      cache[path] = 'cached';
      pushLog({ route: path, action: 'PRELOAD DONE', intent: intent });
      sync();
    }, FETCH_MS);
  }

  // ---- intent handler: only fires when strategy matches the intent ----
  function onIntent(path, intent) {
    if (strategy === 'none') return;       // preloading disabled
    if (strategy === 'viewport') return;   // viewport preloads on mount, not on hover/tap
    if (strategy === intent) startPreload(path, intent);
  }

  // ---- 'viewport' strategy: IntersectionObserver stand-in — preload every
  //      visible link as soon as the strategy is active (eager by design) ----
  React.useEffect(function () {
    if (strategy !== 'viewport') return;
    ROUTES.forEach(function (r) {
      if (r.path !== '/' && !cache[r.path]) startPreload(r.path, 'viewport');
    });
  }, [strategy]);

  // ---- click = navigate. cache hit → INSTANT, miss → LOADING ----
  function navigate(path) {
    setCurrentRoute(path);
    if (cache[path] === 'cached') {
      setNavStatus('INSTANT');
      pushLog({ route: path, action: 'NAVIGATE', intent: 'click', result: 'instant' });
    } else if (cache[path] === 'loading') {
      // preload in-flight → reuse it, still effectively instant
      setNavStatus('INSTANT (reused)');
      pushLog({ route: path, action: 'NAVIGATE', intent: 'click', result: 'reuse' });
    } else {
      setNavStatus('LOADING');
      pushLog({ route: path, action: 'NAVIGATE', intent: 'click', result: 'cold' });
      cache[path] = 'loading';
      sync();
      setTimeout(function () {
        cache[path] = 'cached';
        pushLog({ route: path, action: 'FETCH DONE', intent: 'click' });
        sync();
      }, FETCH_MS);
    }
  }

  function clearAll() {
    cache = {};
    logSeq = 0;
    setLogs([]);
    setCacheSnap({});
    setNavStatus(null);
  }

  return (
    <div className="max-w-3xl mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-1">Preload Strategy Visualizer</h2>
      <p className="text-[#8b949e] text-xs mb-4">
        Pick a strategy, hover/tap the links, then click. Watch the cache + log.
      </p>

      {/* strategy selector */}
      <div data-testid="strategy-bar" className="flex flex-wrap items-center gap-2 mb-4 p-3 bg-[#0d1117] rounded border border-[#30363d]">
        <span className="text-[#8b949e] text-xs uppercase mr-2">strategy</span>
        {STRATEGIES.map(function (s) {
          var active = s === strategy;
          return (
            <button
              key={s}
              data-testid="strategy"
              data-strategy={s}
              onClick={function () { setStrategy(s); }}
              className={"px-3 py-1 rounded text-xs font-mono border transition " + (active ? "bg-[#61dafb] text-[#0d1117] border-[#61dafb] font-bold" : "bg-transparent text-[#61dafb] border-[#30363d] hover:border-[#61dafb]")}
            >
              {s}
            </button>
          );
        })}
        <span data-testid="strategy-active" className="ml-auto text-[#61dafb] text-xs font-mono">active: {strategy}</span>
      </div>

      {/* the links (Home / Users / Settings / Posts) */}
      <div className="mb-4">
        <div className="text-[#8b949e] text-xs uppercase mb-2">Links &mdash; hover / tap / click</div>
        <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
          {ROUTES.map(function (r) {
            var state = cacheSnap[r.path];
            var isCurrent = currentRoute === r.path;
            return (
              <a
                key={r.path}
                href={r.path}
                data-testid="link"
                data-path={r.path}
                data-label={r.label}
                data-cached={state === 'cached' ? 'true' : 'false'}
                onClick={function (e) { e.preventDefault(); navigate(r.path); }}
                onMouseEnter={function () { onIntent(r.path, 'hover'); }}
                onPointerDown={function () { onIntent(r.path, 'tap'); }}
                className="block px-3 py-3 rounded border text-sm font-mono cursor-pointer select-none transition"
                style={{
                  background: isCurrent ? r.hue + '22' : '#0d1117',
                  borderColor: isCurrent ? r.hue : '#30363d',
                  color: state === 'cached' ? r.hue : '#e6edf3'
                }}
              >
                <div className="font-bold">{r.label}</div>
                <div className="text-[10px] text-[#8b949e] mt-0.5">{r.path}</div>
                <div className="text-[10px] mt-1">
                  {state === 'loading' ? '⟳ loading…' : state === 'cached' ? '✓ cached' : '○ idle'}
                </div>
              </a>
            );
          })}
        </div>
      </div>

      {/* nav status */}
      <div className="grid grid-cols-2 gap-3 mb-4">
        <div className="p-3 bg-[#0d1117] rounded border border-[#30363d]">
          <div className="text-[#8b949e] text-xs uppercase mb-1">Current Route</div>
          <div data-testid="current-route" className="text-[#61dafb] text-sm font-mono break-all">{currentRoute}</div>
        </div>
        <div className="p-3 bg-[#0d1117] rounded border border-[#30363d]">
          <div className="text-[#8b949e] text-xs uppercase mb-1">Last Navigation</div>
          <div data-testid="nav-status" data-result={navStatus || ''} className={"text-sm font-mono font-bold " + (navStatus === 'LOADING' ? 'text-[#e74c3c]' : navStatus ? 'text-[#2ecc71]' : 'text-[#8b949e]')}>
            {navStatus || '—'}
          </div>
        </div>
      </div>

      {/* cache state */}
      <div className="p-3 bg-[#0d1117] rounded border border-[#30363d] mb-4">
        <div className="text-[#8b949e] text-xs uppercase mb-2">Cache State</div>
        <div data-testid="cache" className="flex flex-wrap gap-2">
          {ROUTES.map(function (r) {
            var st = cacheSnap[r.path];
            return (
              <span
                key={r.path}
                data-testid="cache-chip"
                data-path={r.path}
                data-state={st || 'empty'}
                className={"px-2 py-1 rounded text-xs font-mono border " + (st === 'cached' ? 'border-[#2ecc71]/60 text-[#2ecc71] bg-[#2ecc71]/10' : st === 'loading' ? 'border-[#f39c12]/60 text-[#f39c12] bg-[#f39c12]/10' : 'border-[#30363d] text-[#8b949e]')}
              >
                {r.path}: {st || 'empty'}
              </span>
            );
          })}
        </div>
      </div>

      {/* preload log (reverse chronological) */}
      <div className="p-3 bg-[#0d1117] rounded border border-[#30363d] mb-4">
        <div className="flex items-center justify-between mb-2">
          <span className="text-[#8b949e] text-xs uppercase">Preload Log</span>
          <button data-testid="clear" onClick={clearAll} className="text-[10px] text-[#8b949e] hover:text-[#e74c3c] border border-[#30363d] rounded px-2 py-0.5">clear cache</button>
        </div>
        <div data-testid="log" className="space-y-1 max-h-44 overflow-y-auto">
          {logs.length === 0 ? (
            <div className="text-[#8b949e] text-xs italic">(no activity yet — hover a link)</div>
          ) : logs.slice().reverse().map(function (row) {
            var color = row.action.indexOf('START') > -1 ? '#f39c12'
              : row.action.indexOf('DONE') > -1 ? '#2ecc71'
              : row.action === 'CACHE HIT' ? '#61dafb'
              : row.action === 'NAVIGATE' ? (row.result === 'cold' ? '#e74c3c' : '#2ecc71')
              : '#8b949e';
            return (
              <div
                key={row.id}
                data-testid="log-row"
                data-action={row.action}
                data-route={row.route}
                data-intent={row.intent}
                data-result={row.result || ''}
                className="text-xs font-mono flex gap-3"
              >
                <span className="text-[#8b949e] w-8">#{row.id}</span>
                <span style={{color: color}} className="font-bold w-32">{row.action}</span>
                <span className="text-[#e6edf3] w-20">{row.route}</span>
                <span className="text-[#8b949e]">intent={row.intent}{row.result ? ' result=' + row.result : ''}</span>
              </div>
            );
          })}
        </div>
      </div>
    </div>
  );
}

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

2 · Babel compiles JSX → element tree

<NavigationDemo/> becomes React.createElement(NavigationDemo). Hovering a link calls onIntent(path,'hover') → if strategy matches, startPreload dedups against cache[path], kicks the setTimeout "fetch", and the log + cache snapshot re-render. A later click reads the same cache[path] — hit → INSTANT.

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

3 · live React (the preloading pipeline, proven)

Hover a link to fire intent (with hover selected), then click it — the navigation is INSTANT because the cache already holds the result. Switch to none, hover a fresh link — nothing preloads; clicking it shows LOADING. The gold-check runs this whole sequence automatically and asserts every step.

live: — · gold: hover Users → preload → click INSTANT · none → hover Settings (no preload) → click LOADING

trigger → dedup → cache → navigate

scenario	what happens	why
`preload="intent"` + hover	mouseenter → after `preloadDelay` → `preloadRoute()`	hover ≈ "I'm about to click" — cheapest signal with real intent
`preload="intent"` + tap	pointerdown/touchstart → preload starts (same code path as hover)	mobile has no hover; `intent` covers both event types
`preload="viewport"`	IntersectionObserver fires → preload every link in view	eager — best for landing pages, costs bandwidth on link farms
two links, same route	only the first triggers a fetch; second logs CACHE HIT	dedup key = route path; in-flight promise is shared
click while preloading	navigation awaits the in-flight preload → reuses result	no double fetch; click never cancels the preload
click after `staleTime`	entry is stale → refetch in background (or block, per `staleReloadMode`)	freshness window balances latency vs. data currency
link leaves viewport, unused	after `gcTime` (default 5min) the entry is garbage-collected	preloads don't leak memory forever