tanstack-router-guide（tanstack 路由器指南）

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:

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

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