TanStack Router: Fully Type-Safe Routing in React

Most React routers treat the URL as an untyped string bag. You navigate to a path, read a param, and hope it exists and has the shape you assumed. On a service I run I lost an afternoon to a rename that left three components pointing at a route that no longer existed — the build passed, the page 404'd in production. TanStack Router is the first router I have used that turns that class of bug into a compile error.

It reached a stable v1 in late 2023 and has been steady in production since. In 2026 it is the router people reach for when they want TypeScript to actually understand their navigation, and it is the foundation under TanStack Start for server-side rendering. This post walks through the three things that make it different: typed params, validated search state, and loaders — then compares file-based and code-based routing so you can pick the right one.

Typed path params, no manual casting

When you define a route with a dynamic segment, the router infers the param name and type from the route definition. You do not annotate anything by hand, and you cannot read a param that the route does not declare. The hook is scoped to the route, so its return type is exactly the params that route owns — no optional-everything, no string-or-undefined guessing.

// src/routes/posts.$postId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  component: PostComponent,
})

function PostComponent() {
  // postId is typed as string — inferred from the route path
  const { postId } = Route.useParams()
  return <div>Post {postId}</div>
}

Search params as validated, typed state

This is the feature that changed how I think about URLs. Search params — the part after the question mark — are usually the messiest state in a React app: pagination, filters, sort order, all serialized as strings and re-parsed everywhere. TanStack Router treats the search string as a first-class, typed object. You declare a validateSearch schema on the route, and from then on the parsed, validated object is what every hook and Link sees.

// src/routes/shop.products.tsx
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const productSearchSchema = z.object({
  page: z.number().catch(1),
  filter: z.string().catch(''),
  sort: z.enum(['newest', 'oldest', 'price']).catch('newest'),
})

export const Route = createFileRoute('/shop/products')({
  validateSearch: (search) => productSearchSchema.parse(search),
  component: Products,
})

function Products() {
  // sort is 'newest' | 'oldest' | 'price', not a loose string
  const { page, filter, sort } = Route.useSearch()
  // ...
}

The use of .catch() instead of .default() is deliberate. .catch() means a malformed or missing param silently falls back to the fallback value instead of throwing a validation error at the user. A shared link with a garbage sort value still renders; it just uses the default. That is almost always what you want for URL state that strangers can edit by hand.

• Writing search state is typed too — navigating with a sort value outside the enum is a compile error, not a silent bad URL.
• The router does structural sharing on search objects, so components only re-render when the specific key they read actually changes.
• You are not tied to Zod — any validator that returns a typed object works, including a plain hand-written function.

Loaders: async data as a route boundary

A route loader hoists async work out of the component. Instead of a useEffect that fires after render, the loader runs as part of resolving the route — in parallel with sibling loaders, with caching, and with preloading when the user shows intent by hovering a link. The loader owns the data boundary, and its return value is inferred into useLoaderData with no manual typing.

The subtle part is how loaders and search params connect. A loader does not automatically re-run when any search param changes — that would refetch on every unrelated filter toggle. You declare which search values the loader depends on with loaderDeps, and only those trigger a reload. This keeps caching correct and avoids the classic waterfall of over-fetching.

// src/routes/posts.tsx
export const Route = createFileRoute('/posts')({
  validateSearch: z.object({
    offset: z.number().int().nonnegative().catch(0),
  }),
  // only `offset` re-triggers the loader
  loaderDeps: ({ search: { offset } }) => ({ offset }),
  loader: async ({ deps: { offset } }) => fetchPosts({ offset }),
  component: Posts,
})

function Posts() {
  const posts = Route.useLoaderData() // typed as the return of fetchPosts
  // ...
}

File-based vs code-based routing

TanStack Router supports both defining routes as files on disk and building the route tree by hand in code. Both are fully type-safe, but they get there differently. File-based routing uses a plugin that reads your route files and generates the route tree plus all the type linkages for you. Code-based routing means you construct the tree yourself, wiring each child to its parent with getParentRoute so the child inherits the parent's types.

The official guidance is unambiguous: file-based routing is the recommended default, and it is what TanStack Start uses. It raises the type-safety ceiling because the generator produces linkages that would be tedious and error-prone to maintain by hand. I reach for code-based routing only when routes must be generated dynamically at runtime — a plugin system, say — where files on disk cannot describe the tree. For everything else, let the plugin do the wiring.

The one setup step that unlocks everything

Typed params and loaders work inside a route without extra ceremony, but to make top-level exports like Link and useNavigate fully typed against your route tree, you register the router with declaration merging. This is the single line that pipes your app's exact route types into the global navigation helpers, so an invalid to prop on a Link becomes a red squiggle in your editor.

// src/main.tsx
const router = createRouter({ routeTree })

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

If you have been fighting stringly-typed navigation and useEffect data fetching, TanStack Router is worth the migration cost. Start with file-based routing, validate every route's search params with a schema, move data fetching into loaders wired through loaderDeps, and add the Register block. The payoff is a codebase where the URL is real, typed state — and where the compiler, not production, tells you when a link breaks.