TanStack Router: typed routes, search state and loaders

TanStack Router v1 treats your routes as typed data. Every path, path param and search param is known to TypeScript, so a typo in a link is a compile error instead of a 404 in production.

There are two ways to declare the tree. File-based routing is the one the docs recommend: a file per route under src/routes/, each exporting a route made with createFileRoute, and a bundler plugin (or the Router CLI) that generates routeTree.gen.ts — the tree plus its types — and keeps the path strings in sync when you move files.

// src/routes/posts.tsx
export const Route = createFileRoute("/posts")({
  component: PostsPage,
});

Code-based routing builds the same tree by hand. It's what you'll see in small examples and tests, and it shows what the generator does for you:

const rootRoute = createRootRoute();
const postsRoute = createRoute({ getParentRoute: () => rootRoute, path: "posts" });
const postRoute = createRoute({ getParentRoute: () => rootRoute, path: "posts/$postId" });

const routeTree = rootRoute.addChildren([postsRoute, postRoute]);
const router = createRouter({ routeTree });

getParentRoute links each route to its parent. At runtime the router uses it to build the route's full path (a child's path is relative to its parent's); in the types, it's how a child inherits its parents' params, search and context. The docs stress the types, but it isn't optional at runtime either: without it, the router throws an invariant error when it builds the tree. addChildren then assembles the tree the router matches against.

One more line makes the global exports — Link, useNavigate, redirect — check against your tree. You register the router's type with the library:

declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

After that, with Router 1.170 and TypeScript 5.9, the first two links fail to compile and the third is the fix:

<Link to="/post">…</Link>             // '"/post"' is not assignable … Did you mean '"/posts"'?
<Link to="/posts/$postId">…</Link>    // Property 'params' is missing
<Link to="/posts/$postId" params={{ postId: "5" }}>…</Link> // ✅

Inside a route's own component, use the route's hooks — Route.useParams(), Route.useSearch(), Route.useLoaderData() — which are typed for that route without any hint.

Fetching in a component starts only after it renders, and a child's fetch starts only after its parent's has finished — a waterfall, with a spinner at each level. A route loader starts loading as soon as the router knows where the user is going, before anything renders. With TanStack Query, the loader doesn't own the data; it makes sure the query cache has it.

// the root route declares what every loader receives
const rootRoute = createRootRouteWithContext<{ queryClient: QueryClient }>()({
  component: () => <Outlet />,
});

const postsQuery = (search: PostsSearch) =>
  queryOptions({ queryKey: ["posts", search], queryFn: () => fetchPosts(search) });

const postsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "posts",
  validateSearch: parsePostsSearch, // the validator from the search-params example
  loaderDeps: ({ search }) => ({ page: search.page, tag: search.tag }),
  loader: ({ context, deps }) =>
    context.queryClient.query({ ...postsQuery(deps), staleTime: "static" }),
  pendingComponent: () => <p>Loading posts…</p>,
  component: function PostsPage() {
    const search = postsRoute.useSearch();
    const { data } = useSuspenseQuery(postsQuery(search));
    return <PostList posts={data.items} />;
  },
});

const router = createRouter({
  routeTree: rootRoute.addChildren([postsRoute]),
  context: { queryClient },
  defaultPreloadStaleTime: 0,
});

Line by line:

• createRootRouteWithContext<{ queryClient }>() (note the double call) types the router context; createRouter must then be given a queryClient, and every loader receives it as context.queryClient.
• loaderDeps lists the search values the loader uses. The loader reads them from deps, and when they change between navigations the router re-runs the loader — "regardless of staleTime", in the docs' words. Return only what the loader uses: returning the whole search reloads on every unrelated param.
• queryClient.query({ ...options, staleTime: "static" }) returns the cached data if there is any and fetches otherwise. That's the read-or-fetch the docs now use in loaders. It replaced queryClient.ensureQueryData(options), which Query v5.102 deprecated (still works, to be removed in v6) — most existing code and older guides use that name. Run side by side headlessly, both called the queryFn once for two loads; a plain query(options) (default staleTime: 0) called it twice.
• Returning the promise makes the router wait for it. The navigation completes when the data is in the cache, so the component never sees a loading state for it.
• useSuspenseQuery(postsQuery(search)) in the component reads the same key — the factory guarantees it — and subscribes to it, so invalidations and refetches still update the page. Its data is never undefined.
• defaultPreloadStaleTime: 0 — the router caches loader results too (preloads are fresh for 30 seconds by default). The docs recommend 0 with an external cache so that Query, not the router, decides whether to fetch.

What the user sees when they click Next (checked against Router 1.170 with a slow server): the page they're on stays on screen while the loader runs; only if it takes longer than pendingMs (default 1 second) does the pendingComponent appear — and then for at least pendingMinMs (default 500 ms), so it doesn't flash.

Checked against TanStack Router 1.170 with TanStack Query 5.104 unless a doc is quoted.

A loader that reads search without loaderDeps

loader: ({ context, location }) => {
  const { page } = location.search as PostsSearch; // ❌ the router doesn't know about this
  return context.queryClient.query({ ...postsQuery({ page }), staleTime: "static" });
},

It works on the first load. But the router keys a loader by pathname plus loaderDeps, so going from ?page=1 to ?page=2 is, as far as it knows, the same loader: it didn't run the loader again in a headless run. The component then asks useSuspenseQuery for page 2, finds nothing cached, and suspends — and the route's pendingComponent appeared at once instead of the old page staying on screen. Same data in the end, plus a loading flash and the waterfall the loader was meant to prevent. Declare loaderDeps and read deps.

loaderDeps: ({ search }) => search

The opposite mistake. Every search param becomes a loader dependency, so toggling a view mode or sort direction that the loader never reads re-runs it. The docs: "only include dependencies you actually use in the loader."

A search param every link must now pass

A plain validateSearch function whose output has a required key — page: number — makes search required on every Link and navigate to that route: <Link to="/posts"> fails to type-check (it did here, even with the function's parameter typed { page?: number }: a plain function's parameter type only becomes the link's input type when it's tagged & SearchSchemaInput, per the route options reference). The Search Params guide's answer is a schema with defaults: Zod v4 or Valibot schemas passed directly (they implement Standard Schema, so the router can tell input from output), or Zod v3 through @tanstack/zod-adapter's zodValidator. Then the link's input type has page optional while the route still reads a number.

Two caches, one owner

The router caches loader results too: navigation staleTime 0, preloads fresh for 30 s, gcTime 5 minutes. With TanStack Query in charge of the data, that's a second layer of freshness rules. The docs' recommendation is defaultPreloadStaleTime: 0, so a preload never short-circuits Query's own decision. And after a mutation you invalidate queries, not routes: the component is subscribed through useSuspenseQuery, so it re-renders when the refetch lands. (router.invalidate() re-runs loaders — useful when loader data lives in the router cache.)

from, and components shared between routes

useSearch({ from: "/posts" }) is typed for that route and throws at runtime if rendered under a different one ("Could not find an active match"). A component used on several routes passes strict: false instead and gets every route's search params merged into one object, each key optional. Inside the route's own file, Route.useSearch() needs no hint.