react-tanstack-router

为 React SPA（Vite/Webpack/Rspack，不适用于 Next.js）实现 TanStack Router：基于文件的路由及自动生成的类型安全、动态路由参数（`$postId`）、使用 Zod/Valibot 验证搜索参数、与 TanStack Query（`ensureQueryData`）集成的加载器（`Route.useLoaderData()`）、带有 `Outlet` 的嵌套路由布局、用于依赖注入的路由上下文、通过 `beforeLoad` 守卫实现受保护路由，以及在意图触发或渲染时预加载。

涵盖完整的 SOLID 模块结构（modules/cores/lib/router/、包含 interfaces//queries//components/ 的功能模块）、从 React Router 迁移（useParams()→Route.useParams()、loader→loader 选项），以及错误边界和 404 处理。不涵盖状态管理（react-state）或表单（react-forms）——它们是独立技能；Next.js 路由请使用 App Router（nextjs-16），而非此技能。

TanStack Router

适用于 React 的 100% 类型安全路由器，支持基于文件的路由、加载器、搜索参数验证，以及与 TanStack Query 深度集成。

Agent 工作流（必须遵循）

在进行任何实现之前，必须并行启动 3 个 Agent，每个分别调用一次 Agent，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有路由和导航模式
2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 TanStack Router 文档
3. mcp__context7__query-docs - 检查基于文件的路由和类型安全模式

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

为什么选择 TanStack Router？

对于需要类型安全路由和搜索参数验证的 React SPA，推荐使用 TanStack Router。

特性	TanStack Router	React Router v7
类型安全	完整推断	自动生成
基于文件的路由	内置	框架模式
搜索参数验证	Zod、Valibot	手动
预加载	意图触发、渲染时	有限
TanStack Query 集成	原生支持	手动

适用场景

• React SPA 使用 Vite、Webpack 或 Rspack → 参见 installation.md
• 需要类型安全路由 → 参见 typescript.md
• 需要搜索参数验证 → 参见 search-params.md
• 使用 TanStack Query 获取数据 → 参见 tanstack-query.md
• 不适用于 Next.js（请改用 App Router）

---

关键规则

1. 始终使用基于文件的路由 - 自动生成类型安全 → file-based-routing.md
2. 始终验证搜索参数 - 将 Zod v4 schema 直接传给 validateSearch（仅在使用 Zod v3 时使用 zodValidator）→ search-params.md
3. 始终使用 Route.useLoaderData() - 不要使用全局的 useLoaderData → hooks.md
4. 始终注册路由器类型 - declare module '@tanstack/react-router' → typescript.md
5. 优先使用加载器而非 useEffect - 在渲染前获取数据 → loaders.md
6. 集成 TanStack Query - 用于缓存、变更和乐观更新 → tanstack-query.md
7. 遵循 SOLID 架构 - 模块、接口、文件大小限制 → solid-react skill

---

快速参考：阅读指南

开始新项目

1. 阅读 installation.md 了解配置
2. 以模板 basic-setup.md 为基础

创建功能模块（帖子、用户等）

1. 遵循 templates/feature-module.md 中的架构
2. 使用 tanstack-query.md 中的查询模式

实现身份验证

1. 阅读 auth-guards.md 了解相关概念
2. 复制模板 auth-protected-routes.md

创建带筛选/搜索的页面

1. 阅读 search-params.md，了解 Zod 验证
2. 复制模板 search-filters.md

创建带嵌套布局的仪表板

1. 阅读 nested-routes.md，了解相关概念
2. 复制模板 dashboard-layout.md

---

项目结构（SOLID 架构）

推荐采用 solid-react skill 中遵循 SOLID 原则的结构。

src/
├── modules/
│   ├── cores/                      # Shared between features
│   │   ├── lib/
│   │   │   ├── router/router.ts    # Router configuration
│   │   │   └── query/client.ts     # QueryClient configuration
│   │   ├── components/layouts/     # Shared layouts
│   │   └── interfaces/             # Shared types
│   └── [feature]/                  # Feature module
│       ├── src/
│       │   ├── interfaces/         # Module types
│       │   ├── queries/            # TanStack Query options
│       │   └── components/         # Module components
│       └── index.ts                # Public exports
├── routes/                         # Route definitions ONLY
│   ├── __root.tsx
│   └── [feature]/
└── routeTree.gen.ts               # Auto-generated (DO NOT MODIFY)

完整模板：templates/basic-setup.md

---

参考指南

概念（references/）- 概念文档

主题	参考文档	适用场景
设置	installation.md	Vite/Webpack 配置、React Router 迁移
文件路由	file-based-routing.md	命名约定、routes/ 结构
URL 参数	route-params.md	动态路由 $postId、解析
搜索参数	search-params.md	Zod 验证、URL 筛选、分页
数据加载	loaders.md	加载器、预加载、TanStack Query 集成
导航	navigation.md	Link、useNavigate、重定向
上下文	route-context.md	依赖注入、QueryClient、用户
布局	nested-routes.md	嵌套布局、Outlet、无路径路由
错误	error-handling.md	错误边界、404、等待状态
懒加载	code-splitting.md	代码拆分、包优化
预加载	preloading.md	预加载意图/渲染、预取
身份验证	auth-guards.md	受保护路由、RBAC、登录重定向
TanStack Query	tanstack-query.md	queryOptions、变更、缓存
SSR	ssr.md	服务端渲染、TanStack Start
TypeScript	typescript.md	类型注册、类型推断、类型安全
开发工具	devtools.md	Router DevTools 设置
Hooks API	hooks.md	useParams、useSearch、useNavigate 等
组件	components.md	Link、Outlet、Navigate、RouterProvider

模板（references/templates/）- 可直接复制粘贴的完整代码

模板	适用场景
basic-setup.md	使用 SOLID 架构启动新项目
feature-module.md	创建完整的功能模块（接口、查询、组件）
auth-protected-routes.md	实现登录、受保护路由、RBAC
search-filters.md	带 URL 筛选、分页和排序的页面
dashboard-layout.md	带侧边栏、标签页和嵌套布局的仪表板

---

核心模式

1. 带上下文的根路由

用于依赖注入的路由器上下文配置。

// src/routes/__root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  component: RootComponent,
})

详情：route-context.md 模板：templates/basic-setup.md

2. 带加载器和 TanStack Query 的文件路由

推荐用于缓存数据加载的模式。

// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postQueryOptions(params.postId)),
  component: PostPage,
})

详情：loaders.md、tanstack-query.md 模板：templates/feature-module.md

3. 使用 Zod 验证搜索参数

通过 URL 实现类型安全的筛选和分页。

// src/routes/posts/index.tsx
const searchSchema = z.object({
  page: z.number().min(1).default(1),
  sort: z.enum(['newest', 'oldest']).default('newest'),
})

export const Route = createFileRoute('/posts/')({
  validateSearch: searchSchema, // Zod v4 = Standard Schema, no adapter
})

详情：search-params.md 模板：templates/search-filters.md

4. 受保护的路由

带重定向的身份验证守卫。

// src/routes/_authenticated/_authenticated.tsx
export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context, location }) => {
    if (!context.user) {
      throw redirect({ to: '/login', search: { redirect: location.href } })
    }
  },
})

详情：auth-guards.md 模板：templates/auth-protected-routes.md

5. 使用 Outlet 实现嵌套路由布局

用于仪表板的嵌套布局。

// src/routes/_dashboard/_dashboard.tsx
export const Route = createFileRoute('/_dashboard')({
  component: () => (
    <DashboardLayout>
      <Outlet />
    </DashboardLayout>
  ),
})

详情：nested-routes.md 模板：templates/dashboard-layout.md

---

最佳实践

推荐做法

模式	参考
使用 Route API（Route.useParams()）	hooks.md
使用 Zod 验证搜索参数	search-params.md
在加载器中使用 ensureQueryData	tanstack-query.md
对链接使用意图预加载	preloading.md
在 interfaces/ 中分离接口	solid-react skill

不推荐做法

反模式	原因	替代方案
使用 useLoaderData() 而不提供 from	不具备类型安全性	Route.useLoaderData()
使用 useEffect 获取数据	并非最佳方案	使用加载器
修改搜索参数	破坏不可变性	navigate({ search: {...} })
跳过错误边界	降低用户体验	添加 errorComponent
在组件中定义接口	产生耦合	interfaces/ 文件夹

---

从 React Router 迁移

完整迁移指南请参阅 installation.md。

React Router	TanStack Router
useParams()	Route.useParams()
useSearchParams()	Route.useSearch()
useLoaderData()	Route.useLoaderData()
loader 函数	loader 选项
action 函数	TanStack Query mutations

---

版本历史

• v1.x - 频繁发布（增量版本控制）
• 重要里程碑：Head/meta 标签、搜索参数中间件、Zod 适配器