react-router

用途

react-router 是 TanStack Router 的 React 绑定包（@tanstack/react-router），用于在 React 应用中构建类型安全的路由。该技能建立在 router-core 之上，建议先阅读 router-core 了解基础概念。

文档特别强调三点：TanStack Router 的类型是完全推断的，不要做类型断言或对推断值加注解；它是客户端优先的，loader 默认在客户端运行而非服务端；不要把它与 react-router-dom/react-router 混淆，它们是 API 完全不同的库。

主要能力

组件

RouterProvider：在 React 树顶部挂载路由器。
Link：类型安全的导航链接，具备 <a> 语义。
Outlet：渲染匹配到的子路由组件。
Navigate：声明式重定向组件。
Await：配合 Suspense 渲染未 await 的 loader Promise 中的延迟数据。
CatchBoundary：组件级错误边界（路由级错误使用 errorComponent 路由选项）。

Hook（均从 @tanstack/react-router 导入）

useRouter()：直接访问路由器实例。
useRouterState()：订阅路由器状态变化；会暴露整个状态，有性能开销，匹配或位置信息建议用 useMatches 和 useLocation。
useNavigate()：编程式导航（用户可点击元素优先用 <Link>）。
useSearch({ from })：读取经过校验的搜索参数。
useParams({ from })：读取路径参数。
useLoaderData({ from })：读取路由 loader 返回的数据。
useMatch({ from })：访问完整的路由匹配（参数、搜索、loader 数据、上下文）。
useMatches()：所有活跃路由匹配的数组（适合面包屑）。
useRouteContext({ from })：读取 beforeLoad 或父路由的上下文。
useBlocker({ shouldBlockFn })：为未保存更改阻止导航。
useCanGoBack()：返回布尔值，检查历史记录中是否有可返回的条目。
useLocation()：当前解析后的位置（pathname、search、hash）。
useLinkProps({ to, params?, search? })：为自定义链接元素获取 <a> 属性。
useMatchRoute()：返回函数 matchRoute({ to }) => match | false。

使用方式

基于 Vite 的文件式路由完整搭建

安装依赖：

npm install @tanstack/react-router
npm install -D @tanstack/router-plugin @tanstack/react-router-devtools

配置 Vite 插件（必须放在 react() 之前）：

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

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

创建根路由（src/routes/__root.tsx），使用 createRootRoute 定义 RootLayout，包含导航 Link、Outlet 和 TanStackRouterDevtools。
创建路由文件（如 src/routes/index.tsx、src/routes/about.tsx），使用 createFileRoute 定义组件。
创建路由器实例并注册类型（src/main.tsx）：

import { RouterProvider, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// REQUIRED — without this, Link/useNavigate/useSearch have no type safety
declare module '@tanstack/react-router' {
  interface Register {
    router: typeof router
  }
}

React 专属模式

使用 createLink 包装 Link 为自定义组件，同时保留类型安全。
跨多个路由复用组件时，为 from 属性传入路由路径的联合类型，避免使用 strict: false。
若路由使用认证上下文（通过 createRootRouteWithContext），认证 Provider 必须是 RouterProvider 的祖先；也可使用 Wrap 路由器选项在不外部包裹的情况下提供上下文。

适用场景

适用于使用 React 构建、需要类型安全路由的应用，尤其是采用 Vite 与文件式路由的项目。文档覆盖搜索参数、数据加载、导航、认证、SSR 等由 router-core 子技能展开的领域。

限制与常见错误

不要在 beforeLoad 或 loader 中使用 React Hook：它们是普通异步函数而非 React 组件，认证状态应通过路由器上下文传递。
不要错误地把 RouterProvider 包在认证 Provider 内部：应只创建一次路由器（用 undefined! 占位），再通过 RouterProvider 的 context 属性注入实时认证；不要在认证变化时重建路由器，否则会重置缓存并重建路由树。
Await/延迟数据缺少 Suspense 边界：Await 需要 <Suspense> 祖先，否则延迟 Promise 没有回退 UI 并会抛出错误。

关于收费、价格、平台支持范围等信息，资料中暂未提供。