Tanstack Router

tanstack-skills/tanstack-skills/plugins/tanstack-router/skills/tanstack-router

作者 tanstack-skills6f5521ecbdfb无许可证35 个星标收录于 2026年10月8日更新于 2026年10月8日仓库8个月前更新

Type-safe routing for React and Solid applications with first-class search params, data loading, and seamless integration with the React ecosystem.

仅含说明Software Development
AI 生成的概览

在 React 和 Solid 应用中使用 TanStack Router 构建类型安全路由的参考指南。

功能
该技能是 TanStack Router 的教学参考，涵盖路由树、基于文件的路由约定、路由配置、数据加载、搜索参数校验、导航、代码分割、预加载、类型安全、鉴权守卫、滚动恢复、路由遮蔽、未找到处理、head 管理以及与 TanStack Query 的集成。它以代码示例和表格呈现，而非可执行工具。文中还列出了最佳实践和常见陷阱。
适用场景
适用于在采用 TanStack Router 的 React 或 Solid 应用中实现或审查路由时。适合处理关于基于文件的路由、带类型的搜索参数、loader、重定向或路由级代码分割的问题。
运行要求
该指南假定存在 JavaScript 或 TypeScript 项目并安装 @tanstack/react-router 包；基于文件的路由可选使用 @tanstack/router-plugin 或 @tanstack/router-cli，另可选用 @tanstack/react-router-devtools 以及用于搜索校验的 Zod。该技能不附带脚本，仅为说明文档。

Overview

TanStack Router is a fully type-safe router for React (and Solid) applications. It provides file-based routing, first-class search parameter management, built-in data loading, code splitting, and deep TypeScript integration. It serves as the routing foundation for TanStack Start (the full-stack framework).

Package: @tanstack/react-router CLI: @tanstack/router-cli or @tanstack/router-plugin (Vite/Rspack/Webpack) Devtools: @tanstack/react-router-devtools

Installation

bash
npm install @tanstack/react-router# For file-based routing with Vite:npm install -D @tanstack/router-plugin# Or standalone CLI:npm install -D @tanstack/router-cli

Core Concepts

Route Trees

Routes are organized in a tree structure. The root route is the top-level layout, and child routes nest underneath.

tsx
import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'
const rootRoute = createRootRoute({  component: RootLayout,})
const indexRoute = createRoute({  getParentRoute: () => rootRoute,  path: '/',  component: HomePage,})
const aboutRoute = createRoute({  getParentRoute: () => rootRoute,  path: '/about',  component: AboutPage,})
const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])const router = createRouter({ routeTree })

File-Based Routing

File-based routing automatically generates the route tree from your file structure. Configure with Vite plugin:

ts
// vite.config.tsimport { defineConfig } from 'vite'import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
export default defineConfig({  plugins: [    TanStackRouterVite(),    // ... other plugins  ],})
File Naming Conventions
File PatternRoute TypeExample Path
__root.tsxRoot layoutN/A (wraps all)
index.tsxIndex route/
about.tsxStatic route/about
$postId.tsxDynamic param/posts/$postId
posts.tsxLayout route/posts/* (layout)
posts/index.tsxNested index/posts
posts/$postId.tsxNested dynamic/posts/123
posts_.$postId.tsxPathless layout/posts/123 (different layout)
_layout.tsxPathless layoutN/A (groups routes)
_layout/dashboard.tsxGrouped route/dashboard
$.tsxSplat/catch-all/*
posts.$postId.edit.tsxDot notation/posts/123/edit
Special Prefixes
  • _ prefix: Pathless routes (layout groups without URL segment)
  • $ prefix: Dynamic path parameters
  • (folder) parentheses: Route groups (organizational, no URL impact)

Route Configuration

Each route can define:

tsx
// routes/posts.$postId.tsximport { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({  // Validation for path params  params: {    parse: (params) => ({ postId: Number(params.postId) }),    stringify: (params) => ({ postId: String(params.postId) }),  },
  // Search params validation  validateSearch: (search: Record<string, unknown>) => {    return {      page: Number(search.page ?? 1),      filter: (search.filter as string) || '',    }  },
  // Data loading  loader: async ({ params, context, abortController }) => {    return fetchPost(params.postId)  },
  // Loader dependencies (re-run loader when these change)  loaderDeps: ({ search }) => ({ page: search.page }),
  // Stale time for cached loader data  staleTime: 5_000,
  // Preloading  preloadStaleTime: 30_000,
  // Error component  errorComponent: PostErrorComponent,
  // Pending/loading component  pendingComponent: PostLoadingComponent,
  // 404 component  notFoundComponent: PostNotFoundComponent,
  // Before load hook (authentication, redirects)  beforeLoad: async ({ context, location }) => {    if (!context.auth.isAuthenticated) {      throw redirect({        to: '/login',        search: { redirect: location.href },      })    }  },
  // Head/meta management  head: () => ({    meta: [{ title: 'Post Details' }],  }),
  // Component  component: PostComponent,})
function PostComponent() {  const { postId } = Route.useParams()  const post = Route.useLoaderData()  const { page, filter } = Route.useSearch()
  return <div>{post.title}</div>}

Data Loading

Route Loaders

tsx
export const Route = createFileRoute('/posts')({  loader: async ({ context }) => {    // Access router context (e.g., queryClient)    const posts = await context.queryClient.ensureQueryData({      queryKey: ['posts'],      queryFn: fetchPosts,    })    return { posts }  },  component: PostsComponent,})
function PostsComponent() {  const { posts } = Route.useLoaderData()  // ...}

Loader Dependencies

Control when loaders re-execute:

tsx
export const Route = createFileRoute('/posts')({  loaderDeps: ({ search: { page, filter } }) => ({ page, filter }),  loader: async ({ deps: { page, filter } }) => {    return fetchPosts({ page, filter })  },})

Deferred Data Loading

Stream non-critical data:

tsx
import { Await, defer } from '@tanstack/react-router'
export const Route = createFileRoute('/dashboard')({  loader: async () => {    const criticalData = await fetchCriticalData()    const deferredData = defer(fetchSlowData())    return { criticalData, deferredData }  },  component: DashboardComponent,})
function DashboardComponent() {  const { criticalData, deferredData } = Route.useLoaderData()
  return (    <div>      <CriticalSection data={criticalData} />      <Suspense fallback={<Loading />}>        <Await promise={deferredData}>          {(data) => <SlowSection data={data} />}        </Await>      </Suspense>    </div>  )}

Context-Based Data Loading

Provide shared dependencies via router context:

tsx
// Create router with contextconst router = createRouter({  routeTree,  context: {    queryClient,    auth: undefined!, // Will be provided by RouterProvider  },})
// In root/app componentfunction App() {  const auth = useAuth()  return <RouterProvider router={router} context={{ auth }} />}
// In routesexport const Route = createFileRoute('/protected')({  beforeLoad: ({ context }) => {    if (!context.auth.user) throw redirect({ to: '/login' })  },  loader: ({ context }) => {    return context.queryClient.ensureQueryData(userQueryOptions())  },})

Search Parameters

Validation

tsx
import { z } from 'zod'
const postSearchSchema = z.object({  page: z.number().default(1),  filter: z.string().default(''),  sort: z.enum(['date', 'title']).default('date'),})
export const Route = createFileRoute('/posts')({  validateSearch: postSearchSchema,  // Or manual validation:  // validateSearch: (search) => postSearchSchema.parse(search),})

Reading Search Params

tsx
function PostsComponent() {  // From route  const { page, filter, sort } = Route.useSearch()
  // Or from any component with useSearch hook  const search = useSearch({ from: '/posts' })}

Updating Search Params

tsx
import { useNavigate } from '@tanstack/react-router'
function Pagination() {  const navigate = useNavigate()  const { page } = Route.useSearch()
  return (    <button      onClick={() =>        navigate({          search: (prev) => ({ ...prev, page: prev.page + 1 }),        })      }    >      Next Page    </button>  )}
// Or via Link component<Link  to="/posts"  search={(prev) => ({ ...prev, page: 2 })}>  Page 2</Link>

Search Param Options

tsx
const router = createRouter({  routeTree,  // Custom serialization  search: {    strict: true, // Reject unknown params  },  // Default search param serializer  stringifySearch: defaultStringifySearch,  parseSearch: defaultParseSearch,})

Navigation

Link Component

tsx
import { Link } from '@tanstack/react-router'
// Static route<Link to="/about">About</Link>
// Dynamic route with params<Link to="/posts/$postId" params={{ postId: '123' }}>  Post 123</Link>
// With search params<Link to="/posts" search={{ page: 2, filter: 'react' }}>  Page 2</Link>
// Active link styling<Link  to="/posts"  activeProps={{ className: 'active' }}  inactiveProps={{ className: 'inactive' }}  activeOptions={{ exact: true }}>  Posts</Link>
// Preloading<Link to="/posts" preload="intent">Posts</Link><Link to="/dashboard" preload="viewport">Dashboard</Link>
// Hash<Link to="/docs" hash="api-reference">API Reference</Link>

Programmatic Navigation

tsx
import { useNavigate, useRouter } from '@tanstack/react-router'
function MyComponent() {  const navigate = useNavigate()  const router = useRouter()
  // Navigate to a route  navigate({ to: '/posts', search: { page: 1 } })
  // Navigate with replace  navigate({ to: '/posts', replace: true })
  // Relative navigation  navigate({ to: '.', search: (prev) => ({ ...prev, page: 2 }) })
  // Go back/forward  router.history.back()  router.history.forward()
  // Invalidate and reload current route  router.invalidate()}

Redirects

tsx
import { redirect } from '@tanstack/react-router'
// In beforeLoad or loaderthrow redirect({  to: '/login',  search: { redirect: location.href },  // Optional status code  statusCode: 301, // Permanent redirect (SSR)})

Navigation Blocking

tsx
import { useBlocker } from '@tanstack/react-router'
function FormComponent() {  const [isDirty, setIsDirty] = useState(false)
  useBlocker({    shouldBlockFn: () => isDirty,    withResolver: true, // Shows confirm dialog  })
  // Or with custom UI  const { proceed, reset, status } = useBlocker({    shouldBlockFn: () => isDirty,  })
  if (status === 'blocked') {    return (      <div>        <p>Are you sure you want to leave?</p>        <button onClick={proceed}>Leave</button>        <button onClick={reset}>Stay</button>      </div>    )  }}

Code Splitting

Automatic (File-Based Routing)

With file-based routing, create a lazy file:

routes/  posts.tsx          # Critical: loader, beforeLoad, meta  posts.lazy.tsx     # Lazy: component, pendingComponent, errorComponent
tsx
// posts.tsx (loaded eagerly)export const Route = createFileRoute('/posts')({  loader: () => fetchPosts(),})
// posts.lazy.tsx (loaded lazily)import { createLazyFileRoute } from '@tanstack/react-router'
export const Route = createLazyFileRoute('/posts')({  component: PostsComponent,  pendingComponent: PostsLoading,  errorComponent: PostsError,})

Manual Code Splitting

tsx
const postsRoute = createRoute({  getParentRoute: () => rootRoute,  path: '/posts',  loader: () => fetchPosts(),}).lazy(() => import('./posts.lazy').then((d) => d.Route))

Preloading

tsx
// Router-level defaultsconst router = createRouter({  routeTree,  defaultPreload: 'intent', // 'intent' | 'viewport' | 'render' | false  defaultPreloadStaleTime: 30_000, // 30 seconds})
// Route-levelexport const Route = createFileRoute('/posts/$postId')({  // Stale time for the loader data  staleTime: 5_000,  // How long preloaded data stays fresh  preloadStaleTime: 30_000,})
// Link-level<Link to="/posts" preload="intent" preloadDelay={100}>  Posts</Link>

Type Safety

Register Router Type

tsx
// Declare module for type inferencedeclare module '@tanstack/react-router' {  interface Register {    router: typeof router  }}

Type-Safe Hooks

All hooks are fully typed based on the route tree:

tsx
// useParams - typed to route's paramsconst { postId } = useParams({ from: '/posts/$postId' })
// useSearch - typed to route's search schemaconst { page } = useSearch({ from: '/posts' })
// useLoaderData - typed to loader returnconst data = useLoaderData({ from: '/posts/$postId' })
// useRouteContext - typed to route contextconst { auth } = useRouteContext({ from: '/protected' })

Route Generics

tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/posts/$postId')({  // TypeScript infers:  // params: { postId: string }  // search: validated search schema type  // loaderData: return type of loader  // context: router context type})

Authenticated Routes

tsx
// __root.tsxexport const Route = createRootRouteWithContext<{  auth: AuthContext}>()({  component: RootComponent,})
// _authenticated.tsx (pathless layout for auth)export const Route = createFileRoute('/_authenticated')({  beforeLoad: ({ context, location }) => {    if (!context.auth.isAuthenticated) {      throw redirect({        to: '/login',        search: { redirect: location.href },      })    }  },})
// _authenticated/dashboard.tsxexport const Route = createFileRoute('/_authenticated/dashboard')({  component: Dashboard, // Only accessible when authenticated})

Scroll Restoration

tsx
const router = createRouter({  routeTree,  // Enable scroll restoration  defaultScrollRestoration: true,})
// Or per-routeexport const Route = createFileRoute('/posts')({  // Scroll to top on navigation  scrollRestoration: true,})
// Custom scroll restoration key<ScrollRestoration  getKey={(location) => location.pathname}/>

Route Masking

Display a different URL than the actual route:

tsx
<Link  to="/photos/$photoId"  params={{ photoId: photo.id }}  mask={{ to: '/photos', search: { photoId: photo.id } }}>  View Photo</Link>
// Or programmaticallynavigate({  to: '/photos/$photoId',  params: { photoId: photo.id },  mask: { to: '/photos', search: { photoId: photo.id } },})

Not Found Handling

tsx
// Global 404const router = createRouter({  routeTree,  defaultNotFoundComponent: () => <div>Page not found</div>,})
// Route-level 404export 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>,})

Head Management

tsx
export const Route = createFileRoute('/posts/$postId')({  head: ({ loaderData }) => ({    meta: [      { title: loaderData.title },      { name: 'description', content: loaderData.excerpt },      { property: 'og:title', content: loaderData.title },    ],    links: [      { rel: 'canonical', href: `https://example.com/posts/${loaderData.id}` },    ],  }),})

Integration with TanStack Query

tsx
import { queryOptions } from '@tanstack/react-query'
const postsQueryOptions = queryOptions({  queryKey: ['posts'],  queryFn: fetchPosts,})
export const Route = createFileRoute('/posts')({  loader: ({ context: { queryClient } }) => {    // Ensure data is in cache, won't refetch if fresh    return queryClient.ensureQueryData(postsQueryOptions)  },  component: PostsComponent,})
function PostsComponent() {  // Use the same query options for reactive updates  const { data: posts } = useSuspenseQuery(postsQueryOptions)  return <PostsList posts={posts} />}

Router Hooks Reference

HookPurpose
useRouter()Access router instance
useRouterState()Subscribe to router state
useParams()Get route path params
useSearch()Get validated search params
useLoaderData()Get route loader data
useRouteContext()Get route context
useNavigate()Get navigate function
useLocation()Get current location
useMatches()Get all matched routes
useMatch()Get specific route match
useBlocker()Block navigation
useLinkProps()Get link props for custom components
useMatchRoute()Check if a route matches

Best Practices

  1. Use file-based routing for most applications - it's simpler and auto-generates the route tree
  2. Validate search params with Zod or custom validators for type safety
  3. Use loaderDeps to control when loaders re-execute based on search param changes
  4. Leverage context for dependency injection (QueryClient, auth state)
  5. Use beforeLoad for authentication guards, not in components
  6. Separate critical vs lazy code - keep loaders in the main file, components in .lazy.tsx
  7. Use preload="intent" on Links for perceived performance
  8. Use staleTime to prevent unnecessary refetches during navigation
  9. Register the router type for full TypeScript inference across the app
  10. Use notFound() instead of conditional rendering for 404 states
  11. Colocate search param logic with routes that own them
  12. Use pathless layouts (_authenticated) for shared auth/layout logic without URL segments

Common Pitfalls

  • Forgetting to register the router type (declare module)
  • Not using loaderDeps when loader depends on search params (causes stale data)
  • Putting auth checks in components instead of beforeLoad (flash of protected content)
  • Not handling the loading state with pendingComponent
  • Using useEffect for data fetching instead of route loaders
  • Mutating search params directly instead of using navigate/Link
  • Not wrapping the app with RouterProvider
  • Forgetting getParentRoute in code-based route definitions

来源与署名

来源：tanstack-skills/tanstack-skills位于plugins/tanstack-router/skills/tanstack-router提交6f5521e

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 tanstack-skills/tanstack-skills 的技能

Tanstack Virtual

tanstack-skills

TanStack Virtual 参考指南，涵盖列表、网格和窗口虚拟化的 API 与用法模式。

Software Development358个月前更新

Tanstack Table

tanstack-skills

使用 TanStack Table 库在 TypeScript 和 JavaScript 中构建无头数据表格与数据网格的参考指南。

Software Development358个月前更新

Tanstack Store

tanstack-skills

TanStack Store 使用参考：跨框架响应式状态库，涵盖 store、派生值、副作用、批量更新与各框架适配器。

Software Development358个月前更新

Tanstack Start

tanstack-skills

TanStack Start 全栈 React 框架参考指南，涵盖服务器函数、中间件、API 路由、SSR 与部署。

Software Development358个月前更新

Tanstack Ranger

tanstack-skills

TanStack Ranger 参考指南，介绍用于在 TS/JS 框架中构建无障碍范围与多范围滑块的 headless 工具。

Software Development358个月前更新

Tanstack Query

tanstack-skills

关于使用 TanStack Query v5 在 TS/JS 应用中管理服务端状态、缓存与数据获取的参考指南。

Software Development358个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新