TanStack Router — Type-Safe Routing for React

Introduction

TanStack Router is a routing library for React that makes every route, path parameter, and search parameter fully type-safe. Created by Tanner Linsley (author of TanStack Query), it rethinks client-side routing with first-class TypeScript support, built-in data loading, and search parameter management as a core feature rather than an afterthought.

What TanStack Router Does

• Provides 100% type-safe routes, params, search params, and navigation APIs
• Validates and serializes URL search parameters with schema libraries like Zod or Valibot
• Supports route-level data loading and preloading with parallel fetching
• Offers file-based routing with automatic code splitting via its Vite plugin
• Handles nested layouts, error boundaries, and pending states declaratively

Architecture Overview

TanStack Router uses a route tree configuration that can be defined manually or generated from a file system convention. The router core maintains a location state machine that matches URL changes against the route tree. Route matches trigger loaders in parallel, and results are cached with configurable stale-while-revalidate semantics. The type system propagates types from route definitions to every hook and component, catching route-related bugs at compile time.

Self-Hosting & Configuration

• Install via npm install @tanstack/react-router and the Vite plugin for file-based routing
• Configure the route tree in routeTree.gen.ts (auto-generated) or manually
• Search parameter schemas are defined per-route using validateSearch
• Data loaders are co-located with route definitions and support beforeLoad guards
• Works with Vite, Webpack, and TanStack Start for full-stack server rendering

Key Features

• End-to-end type safety from route definition to useNavigate and Link components
• Search parameter state management that survives page reloads and sharing
• Built-in devtools for inspecting route matches, params, and cache state
• Automatic route-based code splitting with no manual React.lazy calls
• Middleware system for authentication guards and data prefetching

Comparison with Similar Tools

• React Router — industry standard but search params are untyped strings; TanStack Router types everything
• Next.js App Router — server-centric with RSC; TanStack Router is client-first, server-capable
• Wouter — minimal and lightweight; TanStack Router adds type safety and data loading
• TanStack Query — complements the router for server state; Router handles route-level loading
• vue-router — Vue-specific; TanStack Router targets React with deeper TypeScript integration

FAQ

Q: Can I use TanStack Router with existing React projects? A: Yes. You can adopt it incrementally. The file-based routing is optional—manual route trees work as well.

Q: Does TanStack Router support server-side rendering? A: Yes. TanStack Start builds on TanStack Router to provide full-stack SSR, streaming, and server functions via Nitro.

Q: How does search parameter validation work? A: Each route defines a validateSearch function that parses the URL search string into a typed object. You can use Zod, Valibot, or custom validators.

Q: Is file-based routing required? A: No. File-based routing is a convenience layer. You can define your entire route tree manually in code with full type safety.

Sources

• https://github.com/TanStack/router
• https://tanstack.com/router