tanstack-router-best-practices

TanStack Router 最佳实践

在 React 应用中实现 TanStack Router 模式的综合指南。这些规则有助于优化类型安全、数据加载、导航和代码组织。

适用场景

• 设置应用路由
• 创建新路由和布局
• 实现搜索参数处理
• 配置数据加载器
• 设置代码拆分
• 与 TanStack Query 集成
• 重构导航模式

按优先级划分的规则类别

优先级	类别	规则	影响
CRITICAL	类型安全	4 条规则	防止运行时错误并支持重构
CRITICAL	路由组织	5 条规则	确保路由结构易于维护
HIGH	Router 配置	1 条规则	全局路由默认设置
HIGH	数据加载	6 条规则	优化数据获取和缓存
HIGH	搜索参数	5 条规则	支持类型安全的 URL 状态
HIGH	错误处理	1 条规则	妥善处理 404 和错误
MEDIUM	导航	5 条规则	改善用户体验和无障碍性
MEDIUM	代码拆分	3 条规则	减小打包体积
MEDIUM	预加载	3 条规则	提升感知性能
LOW	路由上下文	3 条规则	支持依赖注入

快速参考

类型安全（前缀：ts-）

• ts-register-router — 注册路由器类型以实现全局推断
• ts-use-from-param — 使用 from 参数进行类型收窄
• ts-route-context-typing — 使用 createRootRouteWithContext 为路由上下文添加类型
• ts-query-options-loader — 在加载器中使用 queryOptions 进行类型推断

Router 配置（前缀：router-）

• router-default-options — 配置路由器默认选项（scrollRestoration、defaultErrorComponent 等）

路由组织（前缀：org-）

• org-file-based-routing — 优先采用文件路由，以遵循约定
• org-route-tree-structure — 遵循分层路由树模式
• org-pathless-layouts — 使用无路径路由实现共享布局
• org-index-routes — 了解索引路由与布局路由的区别
• org-virtual-routes — 了解虚拟文件路由

数据加载（前缀：load-）

• load-use-loaders — 使用路由加载器获取数据
• load-loader-deps — 定义 loaderDeps 以控制缓存
• load-ensure-query-data — 将 ensureQueryData 与 TanStack Query 搭配使用
• load-deferred-data — 拆分关键数据和非关键数据
• load-error-handling — 妥善处理加载器错误
• load-parallel — 利用并行路由加载

搜索参数（前缀：search-）

• search-validation — 始终验证搜索参数
• search-type-inheritance — 利用父级搜索参数类型
• search-middleware — 使用搜索参数中间件
• search-defaults — 提供合理的默认值
• search-custom-serializer — 配置自定义搜索参数序列化器

错误处理（前缀：err-）

• err-not-found — 妥善处理未找到的路由

导航（前缀：nav-）

• nav-link-component — 优先使用 Link 组件进行导航
• nav-active-states — 配置链接的激活状态
• nav-use-navigate — 使用 useNavigate 进行编程式导航
• nav-relative-paths — 了解相对路径导航
• nav-route-masks — 使用路由遮罩实现模态框 URL

代码拆分（前缀：split-）

• split-lazy-routes — 使用 .lazy.tsx 进行代码拆分
• split-critical-path — 将关键配置保留在主路由文件中
• split-auto-splitting — 尽可能启用 autoCodeSplitting

预加载（前缀：preload-）

• preload-intent — 启用基于意图的预加载
• preload-stale-time — 配置预加载过期时间
• preload-manual — 有策略地使用手动预加载

路由上下文（前缀：ctx-）

• ctx-root-context — 在根路由定义上下文
• ctx-before-load — 在 beforeLoad 中扩展上下文
• ctx-dependency-injection — 使用上下文实现依赖注入

使用方法

rules/ 目录中的每个规则文件都包含：

1. 说明 — 为什么这种模式很重要
2. 错误示例 — 应避免的反模式
3. 正确示例 — 推荐的实现方式
4. 适用情境 — 何时应用或跳过此规则

完整参考

详细指南和代码示例请参阅 rules/ 目录中的各个规则文件。