Loader Lifecycle — React Deep Dive

the data-loading pipeline (runs before render)

TanStack Router runs a typed pipeline before the route component mounts. beforeLoad is the gatekeeper (auth, redirects, context); loader fetches the data; the component renders only when both resolve. No useEffect fetch, no loading flicker, no waterfall — and parent/child loaders run in parallel.

step	runs	job	can it abort?
`beforeLoad(ctx)`	1st — before loader	auth checks, `throw redirect()`, set up `context`	yes — throw redirect / error
`loader(ctx)`	2nd — after beforeLoad	fetch data (fetch API, DB, `ensureQueryData`)	yes — throw to bubble to error boundary
`component`	3rd — after loader	`useLoaderData()` / `useRouteContext()`	no — data is already in hand

1 · the lifecycle you write (edit me)

var log = [];

// Simulated route definition — mirrors TanStack Router's createFileRoute('/users/$id')
var route = {
  path: '/users/$id',
  beforeLoad: function (ctx) {
    // 1st: gatekeeper — auth, redirects, context setup
    log.push({ step: 'beforeLoad', detail: 'Checking auth...', status: 'running' });
    return new Promise(function (resolve) {
      setTimeout(function () {
        // throw redirect({ to: '/login' })  <— would abort here if no user
        log.push({ step: 'beforeLoad', detail: 'Auth OK — user: admin', status: 'done' });
        resolve({ user: 'admin' }); // becomes context for loader + component
      }, 300);
    });
  },
  loader: function (ctx) {
    // 2nd: data fetch — ctx.context.user is from beforeLoad
    log.push({ step: 'loader', detail: 'Fetching user ' + ctx.params.id + '...', status: 'running' });
    return new Promise(function (resolve) {
      setTimeout(function () {
        log.push({ step: 'loader', detail: 'User loaded: John Doe', status: 'done' });
        resolve({ name: 'John Doe', email: 'john@example.com' });
      }, 500);
    });
  }
};

function LoaderDemo() {
  var _React$useState = React.useState('idle'),
      phase = _React$useState[0],
      setPhase = _React$useState[1];
  var _React$useState2 = React.useState(null),
      data = _React$useState2[0],
      setData = _React$useState2[1];
  var _React$useState3 = React.useState([]),
      logEntries = _React$useState3[0],
      setLogEntries = _React$useState3[1];

  function runLifecycle() {
    setLogEntries([]);
    log = [];
    setPhase('beforeLoad');
    route.beforeLoad({ params: { id: '42' } })
      .then(function (context) {
        setPhase('loader');
        setLogEntries(log.slice());
        return route.loader({ params: { id: '42' }, context: context });
      })
      .then(function (result) {
        setData(result);
        setPhase('done');
        setLogEntries(log.slice());
      });
  }

  // Map lifecycle phase → status of each conceptual step
  function statusOf(step) {
    if (step === 'beforeLoad') {
      if (phase === 'idle') return 'pending';
      if (phase === 'beforeLoad') return 'running';
      return 'done';
    }
    if (step === 'loader') {
      if (phase === 'idle' || phase === 'beforeLoad') return 'pending';
      if (phase === 'loader') return 'running';
      return 'done';
    }
    // component
    if (phase === 'done') return 'done';
    return 'pending';
  }

  var STATUS_STYLE = {
    pending: 'bg-[#0d1117] text-[#8b949e] border-[#30363d]',
    running: 'bg-[rgba(241,196,15,.12)] text-[#f1c40f] border-[#f1c40f]',
    done: 'bg-[rgba(46,204,113,.12)] text-[#2ecc71] border-[#2ecc71]'
  };
  var STATUS_LABEL = { pending: '○ pending', running: '◔ running', done: '● done' };

  var steps = [
    { key: 'beforeLoad', n: '1', label: 'beforeLoad(ctx)', role: 'auth · redirect · context' },
    { key: 'loader', n: '2', label: 'loader(ctx)', role: 'fetch / DB · ensureQueryData' },
    { key: 'component', n: '3', label: 'Component', role: 'useLoaderData() · useRouteContext()' }
  ];

  var detailFor = {};
  logEntries.forEach(function (e) { detailFor[e.step] = (e.detail || '') + ' [' + e.status + ']'; });

  return (
    <div className="max-w-2xl mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <div className="flex items-center justify-between mb-4">
        <h2 className="text-lg font-bold text-[#61dafb] m-0">
          Route: <code className="text-[13px]">{route.path}</code>
        </h2>
        <button
          data-testid="run"
          className="px-4 py-2 bg-[#61dafb] text-[#0d1117] rounded font-bold text-sm hover:opacity-80"
          onClick={runLifecycle}
        >
          ▶ Run Lifecycle
        </button>
      </div>

      <div className="mb-4 text-xs text-[#8b949e]">
        current phase: <span data-testid="phase" className="text-[#61dafb] font-bold">{phase}</span>
      </div>

      <ol data-testid="timeline" className="space-y-2 mb-4">
        {steps.map(function (s) {
          var st = statusOf(s.key);
          return (
            <li
              key={s.key}
              data-testid="step"
              data-step={s.key}
              data-status={st}
              className={"flex items-start gap-3 p-3 rounded border " + STATUS_STYLE[st]}
            >
              <span className="font-bold text-base leading-none">{s.n}</span>
              <div className="flex-1 min-w-0">
                <div className="font-mono text-sm">{s.label}</div>
                <div className="text-[11px] opacity-80">{s.role}</div>
                {detailFor[s.key] ? (
                  <div data-testid="detail" className="text-[11px] mt-1 italic">{detailFor[s.key]}</div>
                ) : null}
              </div>
              <span className="text-[11px] font-bold whitespace-nowrap">{STATUS_LABEL[st]}</span>
            </li>
          );
        })}
      </ol>

      {phase === 'done' && data ? (
        <div data-testid="loaded-data" className="p-4 rounded border border-[#2ecc71] bg-[rgba(46,204,113,.06)]">
          <div className="text-[11px] uppercase tracking-wide text-[#2ecc71] mb-1">component rendered · useLoaderData()</div>
          <div className="text-[#e6edf3]"><b>{data.name}</b></div>
          <div className="text-[#8b949e] text-sm">{data.email}</div>
        </div>
      ) : (
        <div data-testid="loaded-data" className="p-4 rounded border border-dashed border-[#30363d] text-[#8b949e] text-sm">
          {phase === 'idle' ? 'Click "Run Lifecycle" to start the pipeline.' : 'Loading… component waits for loader.'}
        </div>
      )}
    </div>
  );
}

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

2 · Babel compiles JSX → element tree

<LoaderDemo/> becomes React.createElement(LoaderDemo). The beforeLoad promise chains into loader, which chains into setData + setPhase('done') — the component only flips to "done" when the loader resolves, mirroring how TanStack Router waits before render.

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

3 · live React (the lifecycle, proven)

Click "Run Lifecycle" to fire the simulated pipeline. The timeline tracks beforeLoad (300ms auth check) → loader (500ms fetch) → component. The gold-check does this automatically and asserts the component only shows "John Doe" after both async steps resolve — proving the strict ordering.

phase: — · gold: idle → beforeLoad → loader → done → expect "John Doe"

intent → pattern

intent	pattern	why
check auth / guard a route	`beforeLoad: async ({'>'}) ={'>'} { throw redirect({ to: '/login' }) }`	throws abort the whole navigation — component never mounts
pass data to loader + component	`beforeLoad` returns `{'{ user }'}` → read `context.user`	context flows down the route tree, typed end-to-end
fetch route data	`loader: ({'>'}) ={'>'} fetch(url).then(r={'>'}r.json())`	runs after beforeLoad; result cached per route+params
read loaded data in component	`Route.useLoaderData()` / `useRouteContext()`	typed; no `useEffect`, no loading flicker
re-run loader on search-param change	`loaderDeps: ({'>'}) ={'>'} ({'{ q: deps.search.q }'})`	deep-equal gate; only re-fetches when deps actually change
fine-grained caching + preloading	`ensureQueryData` in loader + `useSuspenseQuery` in component	router primes the Query cache; component reads from cache