Type Inference — React Deep Dive

definition is the single source of truth

A route DEFINITION is where every type is born. TypeScript template-literal types parse the path string ('/users/$id' → {'{ id: string }'}); validateSearch's return type becomes the search type; the loader's return type becomes useLoaderData()'s type. Those types are then registered into the library via declaration merging on the Register interface, so every consumer — <Link>, useNavigate, useParams — is checked against the exact route signature. You write fewer types; the router pipes them through for you.

piece	where the type is born	how it propagates
`params`	path string: `'/users/$id'`	template-literal type → `{'{ id: string }'}`
`search`	`validateSearch` (zod / valibot / arktype)	validator return type → search param type
`loader data`	`loader: ({params}) => fetchUser(...)`	return type → `Route.useLoaderData()`
`context`	`createRootRouteWithContext` + `beforeLoad`	accumulates down the tree → `useRouteContext()`
`<Link>`	consumer (typed by the route)	`Register` merges router types into the module

1 · the type-inference simulator (edit me)

routeTypes models the inferred type signatures. checkLink() is the simulated TS checker: it walks the route's param/search keys against the link's params/search and even validates literal-union values (e.g. tab must be 'posts' | 'comments').

// Route registry — these "type signatures" are what TS would infer from
// createFileRoute('/users/$id')({ validateSearch, loader }).
var routeTypes = {
  '/':             { params: {},                search: {} },
  '/users':        { params: {},                search: { filter: 'string' } },
  '/users/$id':    { params: { id: 'string' },  search: { tab: "'posts' | 'comments'" } },
  '/posts/$postId':{ params: { postId: 'string' }, search: {} }
};

// Validate one value against its inferred type string (e.g. 'string', "'a' | 'b'").
function checkValue(name, value, typeStr) {
  if (typeStr.charAt(0) === "'") {
    var opts = typeStr.split('|').map(function (s) { return s.trim().replace(/'/g, ''); });
    if (opts.indexOf(String(value)) === -1) {
      return name + ': "' + value + '" is not assignable to ' + typeStr;
    }
  }
  return null;
}

// Simulated TS type checker for <Link to params search />.
function checkLink(to, params, search) {
  var errors = [];
  var routeType = routeTypes[to];
  if (!routeType) {
    return { valid: false, errors: ['Unknown route: ' + to + ' (not in Register)'] };
  }
  var expectedParams = Object.keys(routeType.params);
  for (var i = 0; i < expectedParams.length; i++) {
    if (!Object.prototype.hasOwnProperty.call(params, expectedParams[i])) {
      errors.push('Missing param: ' + expectedParams[i]);
    }
  }
  var actualParams = Object.keys(params);
  for (var j = 0; j < actualParams.length; j++) {
    var pk = actualParams[j];
    if (!routeType.params[pk]) {
      errors.push('Unexpected param: ' + pk + ' (route params: ' + (expectedParams.length ? expectedParams.join(', ') : 'none') + ')');
    } else {
      var pvErr = checkValue(pk, params[pk], routeType.params[pk]);
      if (pvErr) errors.push(pvErr);
    }
  }
  var expectedSearch = Object.keys(routeType.search);
  var actualSearch = Object.keys(search);
  for (var k = 0; k < actualSearch.length; k++) {
    var sk = actualSearch[k];
    if (!routeType.search[sk]) {
      errors.push('Unexpected search: ' + sk + ' (route search: ' + (expectedSearch.length ? expectedSearch.join(', ') : 'none') + ')');
    } else {
      var svErr = checkValue(sk, search[sk], routeType.search[sk]);
      if (svErr) errors.push(svErr);
    }
  }
  return { valid: errors.length === 0, errors: errors };
}

function TypeSim() {
  var s = React.useState('/users/$id'), to = s[0], setTo = s[1];
  var p = React.useState('{\n  "id": "42"\n}'), paramsText = p[0], setParamsText = p[1];
  var q = React.useState('{\n  "tab": "posts"\n}'), searchText = q[0], setSearchText = q[1];

  function parse(str) {
    try { return { ok: true, value: JSON.parse(str) }; }
    catch (e) { return { ok: false, error: 'Invalid JSON: ' + e.message }; }
  }
  var pp = parse(paramsText), ss = parse(searchText);
  var result;
  if (!pp.ok) result = { valid: false, errors: [pp.error] };
  else if (!ss.ok) result = { valid: false, errors: [ss.error] };
  else result = checkLink(to, pp.value || {}, ss.value || {});

  var routes = Object.keys(routeTypes);

  return (
    <div>
      <h3 className="text-[#e6edf3] text-sm font-bold mb-2">Route registry (the inferred type signatures)</h3>
      <div style={{ overflowX: 'auto', minWidth: 0 }}>
        <table>
          <tr><th>route</th><th>params type</th><th>search type</th></tr>
          {routes.map(function (r) {
            var t = routeTypes[r];
            var ps = Object.keys(t.params).map(function (k) { return k + ': ' + t.params[k]; }).join(', ');
            var qs = Object.keys(t.search).map(function (k) { return k + '?: ' + t.search[k]; }).join(', ');
            return (
              <tr data-testid="route-row" key={r}>
                <td><code>{r}</code></td>
                <td className="text-[#8b949e]">{'{ ' + (ps || '') + ' }'}</td>
                <td className="text-[#8b949e]">{'{ ' + (qs || '') + ' }'}</td>
              </tr>
            );
          })}
        </table>
      </div>

      <h3 className="text-[#e6edf3] text-sm font-bold mb-2 mt-4">Link builder (checked against the registry)</h3>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-3 mb-3">
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">to (route)</label>
          <select
            data-testid="route-select"
            value={to}
            onChange={function (e) { setTo(e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm"
          >
            {routes.map(function (r) { return <option key={r} value={r}>{r}</option>; })}
          </select>
        </div>
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">params (JSON)</label>
          <textarea
            data-testid="params-input"
            value={paramsText}
            onChange={function (e) { setParamsText(e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm font-mono"
            rows="3" spellCheck="false"
          />
        </div>
        <div>
          <label className="block text-xs text-[#8b949e] mb-1">search (JSON)</label>
          <textarea
            data-testid="search-input"
            value={searchText}
            onChange={function (e) { setSearchText(e.target.value); }}
            className="w-full px-2 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm font-mono"
            rows="3" spellCheck="false"
          />
        </div>
      </div>

      <div
        data-testid="check-result"
        data-valid={result.valid ? 'true' : 'false'}
        className={'p-3 rounded border ' + (result.valid ? 'bg-[rgba(46,204,113,.08)] border-[#2ecc71]' : 'bg-[rgba(231,76,60,.08)] border-[#e74c3c]')}
      >
        {result.valid ? (
          <span className="text-[#2ecc71] font-bold">✓ Valid — types match the route signature</span>
        ) : (
          <div>
            <div className="text-[#e74c3c] font-bold mb-1">✗ Type error(s):</div>
            <ul className="list-disc ml-5 text-[#e74c3c] text-sm">
              {result.errors.map(function (er, i) { return <li key={i}>{er}</li>; })}
            </ul>
          </div>
        )}
      </div>

      <h3 className="text-[#e6edf3] text-sm font-bold mb-2 mt-4">Type chain: definition → inference → consumption</h3>
      <pre className="src">
{"/users/$id  ──define──▶  RouteType { params: { id: string }, search: { tab?: 'posts'|'comments' } }\n" +
"     │\n" +
"     └──register──▶  declare module '@tanstack/react-router' { interface Register { router: typeof router } }\n" +
"     │\n" +
"     └──<Link to='/users/$id' params={{ id }} search={{ tab }} />   ← checked against RouteType\n" +
"     │\n" +
"     └──Route.useLoaderData()  ← typed as the loader return (User)"}
      </pre>
    </div>
  );
}

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

2 · Babel compiles JSX → element tree

<TypeSim/> becomes React.createElement(TypeSim). The route registry + checker run as plain JS; React only re-renders the verdict when to/params/search change.

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

3 · live type-inference simulator (proven)

Edit the route, params, or search above and watch the verdict flip. The gold-check drives it automatically: counts 4 routes, builds a valid link, then flips a param name to trigger a type error.

routes: — · gold: 4 routes → valid link → param-name typo → type error

intent → pattern

intent	pattern	why
declare params from path	`createFileRoute('/users/$id')`	template-literal type parses `$id` → `string`
narrow a param type	`params: {{ parse: z.number() }}`	parsed parent type flows to every child route
declare search params	`validateSearch: zodValidator(z.object({...}))`	validator return type becomes the search type
consume in a component	`Route.useParams()` / `Route.useSearch()`	typed by THIS route's own signature (no `from` needed)
type-safe link	`<Link to="/users/$id" params={ {'id'} } search={ {'tab'} } />`	checked against the `Register`-merged router types
register router types	`declare module {{ ' interface Register {{ router }}' }}`	declaration merging lets types cross the module boundary
shared component, unknown route	`useSearch({{ strict: false }})`	relaxed but accurate union of all routes' search