Route Tree Internals — TanStack Router Deep Dive

URL → component: never direct, always via the tree

A URL like /users/42/posts never reaches a component directly. TanStack Router turns file conventions (or createRoute() calls) into a parent-child route tree, flattens it into a ranked candidate list, and matches the URL segment-by-segment. The matched node's ancestor chain becomes the rendered route-context stack: [Root, Users, UserDetail, UserPosts].

stage	input	output
`1 · compile`	file convention: `users.$id.posts.tsx`	tree node `{'{ name:"UserPosts", path:"/users/$id/posts", parent:"UserDetail" }'}`
`2 · linearize`	the parent-child tree	flat array of full paths, each carrying its ancestor chain
`3 · rank`	flat array	sorted by specificity — static(0) > $param(1) > $splat(2); longer beats shorter on ties
`4 · match`	URL `/users/42/posts`	first ranked candidate whose segments all match → `{'{ route, params:{id:"42"} }'}`

1 · the compiler you write (edit me)

// ── Route definition (mirrors src/routes file conventions) ──────────
//   __root.tsx → Root,  index.tsx → Index,  users.tsx → Users,
//   users.$id.tsx → UserDetail,  users.$id.posts.tsx → UserPosts,
//   settings.tsx → Settings
var routeTree = {
  name: 'Root', path: '/', children: [
    { name: 'Index', path: '/', parent: 'Root' },
    { name: 'Users', path: '/users', parent: 'Root', children: [
      { name: 'UserDetail', path: '/users/$id', parent: 'Users', children: [
        { name: 'UserPosts', path: '/users/$id/posts', parent: 'UserDetail' }
      ] }
    ] },
    { name: 'Settings', path: '/settings', parent: 'Root' }
  ]
};

// ── 1. Tree → flat list (each node keeps its ancestor chain) ─────────
// Root is the implicit wrapper: it stays in every chain but is never the
// terminal match, so it is excluded from the candidate set.
function linearize(node, chain) {
  var newChain = chain.concat([{ name: node.name, path: node.path }]);
  var here = {
    name: node.name,
    path: node.path,
    segments: node.path.split('/').filter(Boolean),
    chain: newChain,
    isRoot: node.name === 'Root'
  };
  var out = [here];
  if (node.children) {
    node.children.forEach(function (child) {
      out = out.concat(linearize(child, newChain));
    });
  }
  return out;
}

// ── 2. Rank by specificity: static(0) > $param(1) > $splat(2) ───────
// Longer paths beat shorter when the shared-prefix ranks tie (PAD=99 sentinels
// the missing positions so a deeper real rank wins over an absent one).
function segRank(seg) {
  if (seg === '$') return 2;
  return seg.charAt(0) === '$' ? 1 : 0;
}
function rankRoutes(routes) {
  var PAD = 99;
  return routes.slice().sort(function (a, b) {
    var sa = a.segments.map(segRank), sb = b.segments.map(segRank);
    var n = Math.max(sa.length, sb.length);
    for (var i = 0; i < n; i++) {
      var ra = i < sa.length ? sa[i] : PAD;
      var rb = i < sb.length ? sb[i] : PAD;
      if (ra !== rb) return ra - rb;
    }
    return 0;
  });
}

// ── 3. Match a URL against the ranked candidates ─────────────────────
// Walk in rank order; first candidate whose segment count AND every segment
// matches wins. $param slices one segment into params; $ captures the rest.
function matchUrl(candidates, pathname) {
  var parts = pathname.split('?')[0].split('/').filter(Boolean);
  for (var i = 0; i < candidates.length; i++) {
    var route = candidates[i];
    if (route.segments.length !== parts.length) continue;
    var params = {}, ok = true;
    for (var j = 0; j < route.segments.length; j++) {
      var seg = route.segments[j];
      if (seg === '$') { params._splat = parts.slice(j).join('/'); break; }
      if (seg.charAt(0) === '$') { params[seg.slice(1)] = parts[j]; }
      else if (seg !== parts[j]) { ok = false; break; }
    }
    if (ok) return { route: route, params: params };
  }
  return null;
}

// Build the working sets once.
var ALL = linearize(routeTree, []);
var CANDIDATES = rankRoutes(ALL.filter(function (r) { return !r.isRoot; }));

function TreeNode(props) {
  var r = props.route;
  var depth = props.depth || 0;
  return (
    <div data-testid="route-node" style={{ paddingLeft: (depth * 18) + 'px', color: r.isRoot ? '#61dafb' : '#e6edf3', fontWeight: r.isRoot ? 700 : 400 }}>
      {r.isRoot ? '◆ ' : '└─ '}{r.name}
      <span style={{ color: '#8b949e', fontWeight: 400 }}>  {r.path}</span>
    </div>
  );
}

function App() {
  var _React$useState = React.useState('/users/42/posts');
  var url = _React$useState[0];
  var setUrl = _React$useState[1];

  var match = matchUrl(CANDIDATES, url);
  var name = match ? match.route.name : 'no match';
  var params = match ? match.params : {};
  var chain = match ? match.route.chain.map(function (c) { return c.name; }).join(' → ') : '—';
  var paramKeys = Object.keys(params);

  return (
    <div className="space-y-5">
      {/* 1 · the tree */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">route tree (file convention → nodes)</div>
        <div className="bg-[#0d1117] border border-[#30363d] rounded p-3 text-[13px]">
          {ALL.map(function (r) { return <TreeNode key={r.name} route={r} depth={r.chain.length - 1} />; })}
        </div>
      </div>

      {/* 2 · linearized + ranked candidates */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">linearized + ranked (match order)</div>
        <div className="bg-[#0d1117] border border-[#30363d] rounded p-3 text-[13px] space-y-1" data-testid="candidates">
          {CANDIDATES.map(function (r, i) {
            return (
              <div data-testid="candidate" key={r.name}>
                <span className="text-[#8b949e]">{i + 1 + '. '}</span>
                <span className="text-[#e6edf3]">{r.name}</span>
                <span className="text-[#8b949e]">  {r.path}</span>
                <span className="text-[#61dafb]">  rank=[{r.segments.map(segRank).join(',')}]</span>
              </div>
            );
          })}
        </div>
      </div>

      {/* 3 · URL input */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">try a URL</div>
        <input
          data-testid="url-input"
          className="w-full px-3 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm outline-none focus:border-[#61dafb]"
          value={url}
          onChange={function (e) { setUrl(e.target.value); }}
          placeholder="/users/42/posts"
        />
        <div className="flex flex-wrap gap-2 mt-2">
          {['/users/42/posts', '/users/7', '/settings', '/', '/nope'].map(function (u) {
            return (
              <button key={u} data-testid="quick" data-url={u}
                className="px-2 py-1 text-xs bg-[#161b22] border border-[#30363d] rounded text-[#61dafb] hover:border-[#61dafb]"
                onClick={function () { setUrl(u); }}>{u}</button>
            );
          })}
        </div>
      </div>

      {/* 4 · match result */}
      <div>
        <div className="text-xs uppercase tracking-wide text-[#61dafb] mb-2">match result</div>
        <div className="bg-[#0d1117] border border-[#30363d] rounded p-3 text-[13px] space-y-2">
          <div>matched route: <span data-testid="match-name" data-name={name} className="text-[#61dafb] font-bold">{name}</span></div>
          <div>params: <span data-testid="match-params" data-json={JSON.stringify(params)} className="text-[#2ecc71]">{paramKeys.length ? paramKeys.map(function (k) { return k + '=' + params[k]; }).join(', ') : '(none)'}</span></div>
          <div>route chain: <span data-testid="match-chain" className="text-[#e6edf3]">{chain}</span></div>
        </div>
      </div>
    </div>
  );
}

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

2 · Babel compiles JSX → element tree

<App/> becomes React.createElement(App). Each render re-runs matchUrl(CANDIDATES, url) against the pre-built, pre-ranked candidate list — the same linearize-once / match-many shape TanStack uses at runtime.

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

3 · live React (the matching pipeline, proven)

Type a URL (or click a quick button). The gold-check drives the input directly: /users/42/posts → asserts UserPosts + id=42, then /settings → asserts Settings. That proves ranking put the right candidate first and $id was sliced into params.

tree nodes: — · gold: 6 nodes → /users/42/posts→UserPosts{id:42} → /settings→Settings

intent → pattern

intent	pattern	why
static beats dynamic	`/users/new` before `/users/$id`	rank 0 < rank 1 — static segment wins the same-length tie
capture one segment	`/users/$id` → `params.id`	$ matches exactly until the next `/`
capture the rest	`/files/$` → `params._splat`	trailing $ is a splat/wildcard, consumes everything left
resolve ambiguity	`params: { priority: 10, parse }`	higher priority candidate tried first; parse()=false falls through
build the context stack	matched node `.chain` → `[Root, …, leaf]`	each ancestor's layout/outlet wraps the next — the route-context chain