tanstack-router-guide

TanStack Router Guide (React)

TanStack Router is a fully type-safe, file-based router for React. It provides first-class search param APIs, built-in data loading with SWR caching, automatic code splitting, and 100% inferred TypeScript types. Designed for client-first SPAs with optional SSR support.

Install

npm install @tanstack/react-router
npm install -D @tanstack/router-plugin
# Optional: devtools
npm install @tanstack/react-router-devtools

Quick Start with Vite (Recommended)

1. Configure Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
    react(), // Must come AFTER tanstackRouter
  ],
})

2. Create root route:

// src/routes/__root.tsx
import { createRootRoute, Link, Outlet } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'

export const Route = createRootRoute({
  component: () => (
    <>
      <nav>
        <Link to="/" activeProps={{ className: 'font-bold' }}>Home</Link>
        <Link to="/about" activeProps={{ className: 'font-bold' }}>About</Link>
      </nav>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
})

3. Create routes:

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

export const Route = createFileRoute('/')({
  component: () => <div>Welcome Home!</div>,
})

// src/routes/about.tsx
export const Route = createFileRoute('/about')({
  component: () => <div>About Page</div>,
})

4. Mount the router:

// src/main.tsx
import { StrictMode } from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// Register router type globally for type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>,
)

File-Based Routing (Naming Conventions)

Routes live in src/routes/ and file names determine URL paths:

File Name	URL Path	Purpose
__root.tsx	N/A	Root layout (always rendered)
index.tsx	/	Index route
about.tsx	/about	Static route
posts.tsx	/posts	Layout route (renders Outlet)
posts.index.tsx	/posts	Index for /posts
posts.$postId.tsx	/posts/:postId	Dynamic segment
_auth.tsx	N/A	Pathless layout (wraps children, no URL)
_auth.dashboard.tsx	/dashboard	Child of pathless layout
posts_.$postId.edit.tsx	/posts/:postId/edit	Non-nested (escapes parent layout)
files.$.tsx	/files/*	Splat/catch-all route
posts.{-$category}.tsx	/posts/:category?	Optional path parameter
-utils.tsx	N/A	Excluded from routing
(group)/login.tsx	/login	Route group (organizational only)

The plugin auto-generates routeTree.gen.ts - commit this file but never edit it manually.

Navigation

import { Link, useNavigate } from '@tanstack/react-router'

// Declarative - Link component
<Link to="/posts/$postId" params={{ postId: '123' }}>View Post</Link>
<Link to="/posts" search={{ page: 2, sort: 'asc' }}>Page 2</Link>
<Link to=".." from="/posts/$postId">Back to Posts</Link>

// Active styling
<Link to="/about" activeProps={{ className: 'active' }} inactiveProps={{ className: 'dim' }}>
  About
</Link>

// Programmatic - useNavigate
const navigate = useNavigate()
navigate({ to: '/posts/$postId', params: { postId: '123' } })
navigate({ to: '/posts', search: (prev) => ({ ...prev, page: 2 }) })
navigate({ to: '..', from: '/posts/$postId' }) // Relative

Search Params (Validated & Type-Safe)

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

export const Route = createFileRoute('/posts')({
  validateSearch: z.object({
    page: z.number().catch(1),
    sort: z.enum(['asc', 'desc']).optional(),
    filter: z.string().optional(),
  }),
  component: PostsPage,
})

function PostsPage() {
  const { page, sort, filter } = Route.useSearch() // Fully typed
  const navigate = Route.useNavigate()

  return (
    <button onClick={() => navigate({ search: (prev) => ({ ...prev, page: prev.page + 1 }) })}>
      Next Page
    </button>
  )
}

Search Middlewares - retain or strip params across navigations:

import { retainSearchParams, stripSearchParams } from '@tanstack/react-router'

export const Route = createFileRoute('/posts')({
  validateSearch: z.object({ page: z.number().catch(1), q: z.string().optional() }),
  search: {
    middlewares: [
      retainSearchParams(['q']),        // Keep 'q' across navigations
      stripSearchParams({ page: 1 }),    // Strip 'page' when it equals default
    ],
  },
})

Data Loading

// Basic loader with path params
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    return { post }
  },
  component: PostPage,
})

function PostPage() {
  const { post } = Route.useLoaderData() // Fully typed
  return <div>{post.title}</div>
}

// Loader with search-param dependencies
export const Route = createFileRoute('/posts')({
  validateSearch: z.object({ page: z.number().catch(1) }),
  loaderDeps: ({ search }) => ({ page: search.page }),
  loader: async ({ deps }) => fetchPosts(deps.page),
  component: PostsPage,
})

Key loader options: staleTime (SWR cache duration), shouldReload (control when to re-fetch), pendingMs/pendingMinMs (loading indicator timing), gcTime (garbage collection), loaderDeps (search-param keying).

Optional Path Parameters

Use {-$paramName} syntax for segments that may or may not exist:

// src/routes/posts.{-$category}.tsx -> /posts or /posts/tech
export const Route = createFileRoute('/posts/{-$category}')({
  component: () => {
    const { category } = Route.useParams() // category: string | undefined
    return <div>{category ? `Posts in ${category}` : 'All Posts'}</div>
  },
})

// Navigation: pass undefined to omit the segment
<Link to="/posts/{-$category}" params={{ category: undefined }}>All Posts</Link>
<Link to="/posts/{-$category}" params={{ category: 'tech' }}>Tech Posts</Link>

Router Context (Dependency Injection)

import { createRootRouteWithContext } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'

interface RouterContext {
  queryClient: QueryClient
  auth: AuthState
}

// Root route
const rootRoute = createRootRouteWithContext<RouterContext>()({
  component: RootComponent,
})

// Use in any route
export const Route = createFileRoute('/posts')({
  beforeLoad: ({ context }) => {
    // context.queryClient and context.auth available here
  },
  loader: ({ context }) => context.queryClient.ensureQueryData(postsQueryOptions()),
})

// Provide context when creating router
const router = createRouter({
  routeTree,
  context: { queryClient, auth: { user: null } },
})

Authentication (Protected Routes)

// src/routes/_auth.tsx - Pathless layout for protected routes
export const Route = createFileRoute('/_auth')({
  beforeLoad: async ({ context, location }) => {
    if (!context.auth.user) {
      throw redirect({
        to: '/login',
        search: { redirect: location.href },
      })
    }
  },
  component: () => <Outlet />,
})

// src/routes/_auth.dashboard.tsx - Protected route
export const Route = createFileRoute('/_auth/dashboard')({
  component: () => <div>Protected Dashboard</div>,
})

Error Handling

import { notFound } from '@tanstack/react-router'

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId)
    if (!post) throw notFound()
    return { post }
  },
  notFoundComponent: () => <div>Post not found!</div>,
  errorComponent: ({ error, reset }) => (
    <div>
      <p>Error: {error.message}</p>
      <button onClick={reset}>Retry</button>
    </div>
  ),
})

// Global defaults on router
const router = createRouter({
  routeTree,
  defaultNotFoundComponent: () => <div>Page not found</div>,
  defaultErrorComponent: ({ error }) => <div>Error: {error.message}</div>,
})

Essential Hooks

Hook	Purpose
Route.useSearch()	Current validated search params
Route.useParams()	Current path params
Route.useLoaderData()	Data from route loader
Route.useRouteContext()	Route's context
Route.useNavigate()	Navigate from current route
useNavigate()	Navigate from any component
useRouter()	Access router instance
useRouterState()	Reactive router state
useMatch({ from: '/route' })	Match data for specific route
useBlocker()	Block navigation (dirty forms)

See references/api-hooks.md for all 19 hooks with full signatures.

Key Rules

• Plugin order: tanstackRouter() must come BEFORE react() in Vite config
• Commit routeTree.gen.ts: It's runtime code, not a build artifact
• Module declaration: Always register router type for global type inference
• Export as Route: File-based routes must export const Route = createFileRoute(...)
• Pathless layouts: Prefix with _ (e.g., _auth.tsx) for layout-only routes
• Non-nested routes: Use _ suffix to escape parent layout (e.g., posts_.$id.edit.tsx)
• Ignore generated file: Add routeTree.gen.ts to .prettierignore, .eslintignore
• Route matching order: Index > Static > Dynamic > Splat (automatic)
• Don't export route properties: Exported components/loaders break code splitting
• Validation adapters: Valibot/ArkType work directly; Zod needs zodValidator adapter
• Outlet required: Every route with children must render <Outlet />; routes without a component auto-render <Outlet />
• Type safety tip: Use Route.useX() methods over standalone hooks for automatic type inference

Reference Files

API

• references/api-hooks.md — All 19 hooks with signatures, options, and examples
• references/api-components.md — Link, Outlet, Await, Block, HeadContent, CatchNotFound, and more
• references/api-functions.md — createRouter, createFileRoute, redirect, notFound, linkOptions, search middleware
• references/api-router-instance.md — Router instance methods, events, and route type API
• references/api-types.md — NavigateOptions, RouterState, RouteMatch, type utilities, deprecated items

Patterns

• references/patterns-params.md — Path parameters, search params (Zod/Valibot/ArkType), loaderDeps, middlewares
• references/patterns-links-blocking.md — Link options, custom links, navigation blocking, history types
• references/patterns-data.md — Data loading, mutations, TanStack Query integration, not-found handling
• references/patterns-auth.md — Authentication, RBAC, router context, preloading strategies

Configuration

• references/config-bundlers.md — Vite, Webpack, Rspack, esbuild, Router CLI setup and plugin options
• references/config-routing.md — File naming conventions, route matching, code-based routing
• references/config-virtual-routes.md — Virtual file routes, physical routes, __virtual.ts subtrees
• references/config-router-options.md — All createRouter() options: core, preloading, data loading, search, scroll, URL behavior
• references/config-route-options.md — All createFileRoute/createRoute options: components, search, loader, lifecycle, head, SSR
• references/config-devtools.md — DevTools modes, production devtools, IDE configuration

Advanced

• references/advanced-ssr.md — SSR streaming/non-streaming, dehydration/hydration, deferred data
• references/advanced-code-splitting.md — Automatic/manual splitting, split groupings, lazy routes
• references/advanced-url-features.md — URL rewrites, route masking, custom search serialization
• references/advanced-optimization.md — Type safety, TS performance tips, render optimizations, view transitions
• references/advanced-head-scroll.md — Document head management, scroll restoration, i18n

Operations

• references/troubleshooting.md — FAQ, common errors, debugging guide, performance issues
• references/deployment-integrations.md — Deployment (8 platforms), environment variables, framework integrations
• references/testing-migration.md — Testing setup, route testing patterns, migration guides