mcpField
T
tanstack-router-best-practices

tanstack-router-best-practices

github.com/pedronauck开发651110 次安装6 天前更新
代码仓库

关于 tanstack-router-best-practices

面向 React 应用的 TanStack Router 实践指南，供开发者参考。它以分级规则和示例讲解类型安全、路由组织、数据加载与导航等模式。

主要功能

  1. 01路由与类型安全指南
  2. 02基于文件的路由组织模式
  3. 03Loader 与查询数据实践
  4. 04搜索参数验证
  5. 05导航与错误处理
  6. 06代码拆分与预加载

适用场景

  1. 01为 React 应用设置路由
  2. 02检查 Loader 和搜索参数模式
  3. 03重构路由结构与导航

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pedronauck/skills --skill tanstack-router-best-practices

安装后在 Claude Code 中输入/tanstack-router-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

rules/
ctx-root-context.md
err-not-found.md
load-ensure-query-data.md
load-parallel.md
load-use-loaders.md
nav-link-component.md
nav-route-masks.md
org-virtual-routes.md
preload-intent.md
router-default-options.md
search-custom-serializer.md
search-validation.md
split-lazy-routes.md
ts-register-router.md
ts-use-from-param.md

详细介绍

TanStack Router 最佳实践

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

适用场景

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

按优先级划分的规则类别

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

快速参考

类型安全（前缀：ts-）
  • ts-register-router — 注册 Router 类型以支持全局类型推断
  • ts-use-from-param — 使用 from 参数缩小类型范围
  • ts-route-context-typing — 使用 createRootRouteWithContext 为路由上下文指定类型
  • ts-query-options-loader — 在加载器中使用 queryOptions 进行类型推断
Router 配置（前缀：router-）
  • router-default-options — 配置 Router 默认选项（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/ 目录中的各个规则文件。

评论

支持 Markdown