tanstack-router

TanStack Router

当工作涉及 TanStack Router 时使用此技能，尤其是涉及 @tanstack/react-router、src/routes/**、src/router.tsx、路由树生成、类型化导航或路由自身的数据加载时。

工作流

1. 首先检查本地 Router 的结构：
   • @tanstack/react-router、@tanstack/router-plugin、开发工具、适配器以及任何 Query/SSR 集成的包版本。
   • 路由模式：基于文件、基于代码、虚拟文件路由或混合模式。
   • 路由入口：src/routes/__root.tsx、src/router.tsx、生成的 src/routeTree.gen.ts、应用/客户端入口，以及存在时的 SSR 入口。
   • 会影响行为的路由选项：validateSearch、params、beforeLoad、loaderDeps、loader、pendingComponent、errorComponent、notFoundComponent、search.middlewares、staleTime、gcTime、preload 和 ssr 集成。
2. 对于当前行为、新版本、SSR、测试、路由生成或迁移，查阅最新文档。从 source-map.md 开始。
3. 有关设置、安装、路由树生成、文件命名，以及在路由旁放置非路由模块（-components、-hooks、-lib 等），请参阅 setup-route-trees.md。
4. 有关链接、导航、参数、搜索参数、掩码和 URL 状态，请参阅 navigation-url-state.md。
5. 有关加载器、上下文、身份验证守卫、Query 集成、错误/未找到边界、预加载和延迟数据，请参阅 loaders-context-errors.md。
6. 有关 SSR、部署重写、测试、开发工具、ESLint 和生产环境检查，请参阅 production-testing.md。

实现判断

• 除非仓库已采用基于代码的路由，或用户另有要求，否则优先使用基于文件的路由。
• 将 routeTree.gen.ts 视为生成产物。不要手动编辑；应通过仓库的打包工具/CLI 流程重新生成。
• 将路由自身的 UI/钩子/辅助函数放在带连字符前缀的文件夹中（routeFileIgnorePrefix，默认为 -）。不要在 routes/ 下放置无此前缀的非路由文件。
• 保持导航类型安全。不要通过将参数或查询字符串插入 to 来构造路径；应分别传入 to、params、search 和 hash。
• 每个读取 URL 搜索状态的路由都应声明 validateSearch；使用 loaderDeps 仅暴露加载器实际使用的搜索字段。
• 使用 beforeLoad 实现路由的用户体验控制、重定向和上下文扩充。不要将路由守卫视为私有数据的授权边界。
• 将路由共享的依赖放入 Router 上下文；不要直接在 beforeLoad 或 loader 中调用 React 钩子。
• 明确决定使用 Router 内置的 SWR 加载器缓存，还是使用 TanStack Query 之类的外部缓存。当由 Query 管理新鲜度时，将 Router 预加载的过期时间设为 0，并由 Query 负责请求去重。对于 Query 5.102+，通过 queryClient.query(...) 加载；ensureQueryData / prefetchQuery / fetchQuery 已弃用。
• 在 React 中，将 errorComponent / onCatch 的错误类型设为 unknown，并在读取 message 前进行类型收窄。
• 在加载器中使用 notFound() 处理未找到的资源，以确保加载器数据类型正确，并避免 UI 闪烁。

验证

优先使用仓库现有的检查。对于有实质影响的 Router 改动，请执行以下相关检查：

• 通过开发/构建流程或明确的 Router CLI 命令生成路由树。
• 对路由引用、参数、搜索状态、加载器和上下文进行类型检查。
• 针对路由匹配、搜索验证、加载器、身份验证重定向、未找到/错误边界和导航进行定向测试。
• 在浏览器中进行冒烟测试，检查直接加载、客户端导航、前进/后退、刷新以及生产环境中的重写行为。