TanStack Router

TanStack Router is a router for React applications that treats type safety as a first-class concern: route paths, params, search params, and loader data are all inferred end-to-end, so typos and shape mismatches surface at compile time instead of in production. Built on top of the framework-agnostic @tanstack/router-core, it layers in schema-validated search params, built-in request caching and preloading, nested layouts, and first-class error and not-found boundaries.

Beyond client-side routing, it is also the foundation for TanStack Start, a full-stack framework adding SSR, streaming, and server functions on top of the same route tree. Teams adopt it either as a drop-in replacement for React Router with stronger typing, or as the routing layer of a full-stack TanStack Start application.

What You Get

• End-to-end type-safe routes, path params, and loader data inferred from your route tree — no manual generic annotations
• Schema-driven search-param validation and parsing (Zod, Valibot, ArkType adapters included)
• Built-in route loader caching, preloading, and stale-while-revalidate style invalidation
• Nested layouts, pathless layout routes, and route-level pending/error/not-found boundaries
• A file-based route generator (@tanstack/router-plugin / router-cli) that keeps the route tree in sync with your routes/ directory
• Devtools panel for inspecting the route tree, matches, and loader cache in real time

Common Use Cases

• Replacing React Router in a client-rendered SPA to get compile-time-checked links, params, and search state
• Building the routing layer of a TanStack Start full-stack app with SSR, streaming, and server functions
• Apps with complex, validated URL state (filters, pagination, sort) that need search params treated as typed application state rather than raw strings
• Migrating from a loosely-typed router where param/typo bugs regularly reach production

Under The Hood

Architecture TanStack Router splits cleanly into a framework-agnostic core (@tanstack/router-core, ~3,275 lines in router.ts plus a ~2,129-line route.ts) and thin per-framework adapters (@tanstack/react-router’s router.ts is only ~119 lines, mostly type declaration merging and defaults). The core owns the route tree, matching, loader/cache lifecycle (load-matches.ts, lru-cache.ts), history integration (via the internal @tanstack/history package), and structural-sharing logic (structuralSharing.ts) that avoids re-rendering matches whose data hasn’t changed. The React package layers hooks (useLoaderData, useMatch, useNavigate, useSearch, etc.), a RouterProvider, and SSR entry points (src/ssr/) on top of that core, and the same core is reused by the Solid and Vue adapters in the same monorepo — evidence of a deliberate framework-agnostic core / thin-adapter split.

Tech Stack Pure TypeScript (98% of the codebase) built with Vite, tested with Vitest (including a dedicated test:perf benchmark suite via vitest bench), and packaged as dual ESM/CJS output with publint/attw build-time checks for package export correctness. Runtime dependencies are deliberately minimal (@tanstack/history, @tanstack/react-store, @tanstack/router-core, isbot), with React 18/19 as peer dependencies and adapters for Zod, Valibot, and ArkType shipped as separate optional packages rather than hard dependencies.

Code Quality The repo carries 71 test files across packages/react-router and packages/router-core alone, plus type-level tests run against five separate TypeScript versions (test:types:ts55 through ts60) to guard the type inference that is the library’s core value proposition. noUncheckedIndexedAccess and checkJs are enabled in the shared tsconfig.json, and ESLint runs as its own test target (test:eslint) in every package, indicating quality gates are enforced per-package rather than only at the repo root.

API Design The public API favors typed hooks (useLoaderData, useParams, useSearch) over generic string-keyed access, and file-based routing removes most manual route-tree boilerplate for common cases — the generator infers types from file names/paths automatically. The tradeoff is a real learning curve: getting full type inference requires understanding route tree composition, createFileRoute/createRoute generics, and search-param schema wiring, which is steeper than a conventional untyped router but is offset by 57 runnable example apps and ~244 documentation files covering guides for each feature area.