Back to Details

tanstack-router-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack Router Best Practices

TanStack Router 最佳实践

Comprehensive guidelines for implementing TanStack Router patterns in React applications. These rules optimize type safety, data loading, navigation, and code organization.
在 React 应用中实现 TanStack Router 模式的综合指南。这些规则可优化类型安全性、数据加载、导航和代码组织。

When to Apply

适用场景

  • Setting up application routing
  • Creating new routes and layouts
  • Implementing search parameter handling
  • Configuring data loaders
  • Setting up code splitting
  • Integrating with TanStack Query
  • Refactoring navigation patterns
  • 搭建应用路由
  • 创建新路由与布局
  • 实现搜索参数处理
  • 配置数据加载器
  • 搭建代码分割
  • 与 TanStack Query 集成
  • 重构导航模式

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryRulesImpact
CRITICALType Safety4 rulesPrevents runtime errors and enables refactoring
CRITICALRoute Organization5 rulesEnsures maintainable route structure
HIGHRouter Config1 ruleGlobal router defaults
HIGHData Loading6 rulesOptimizes data fetching and caching
HIGHSearch Params5 rulesEnables type-safe URL state
HIGHError Handling1 ruleHandles 404 and errors gracefully
MEDIUMNavigation5 rulesImproves UX and accessibility
MEDIUMCode Splitting3 rulesReduces bundle size
MEDIUMPreloading3 rulesImproves perceived performance
LOWRoute Context3 rulesEnables dependency injection
优先级类别规则数量影响
关键类型安全4 条规则防止运行时错误并支持重构
关键路由组织5 条规则确保路由结构可维护
高路由器配置1 条规则全局路由器默认设置
高数据加载6 条规则优化数据获取与缓存
高搜索参数5 条规则实现类型安全的 URL 状态
高错误处理1 条规则优雅处理 404 与错误
中导航5 条规则提升用户体验与可访问性
中代码分割3 条规则减小包体积
中预加载3 条规则提升感知性能
低路由上下文3 条规则支持依赖注入

Quick Reference

快速参考

Type Safety (Prefix: 
ts-
)

类型安全（前缀：
ts-
）

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

Router Config (Prefix: 
router-
)

路由器配置（前缀：
router-
）

  • router-default-options
    — Configure router defaults (scrollRestoration, defaultErrorComponent, etc.)
  • router-default-options
    — 配置路由器默认选项（scrollRestoration、defaultErrorComponent 等）

Route Organization (Prefix: 
org-
)

路由组织（前缀：
org-
）

  • org-file-based-routing
    — Prefer file-based routing for conventions
  • org-route-tree-structure
    — Follow hierarchical route tree patterns
  • org-pathless-layouts
    — Use pathless routes for shared layouts
  • org-index-routes
    — Understand index vs layout routes
  • org-virtual-routes
    — Understand virtual file routes
  • org-file-based-routing
    — 优先使用基于文件的路由约定
  • org-route-tree-structure
    — 遵循分层路由树模式
  • org-pathless-layouts
    — 使用无路径路由实现共享布局
  • org-index-routes
    — 理解索引路由与布局路由的区别
  • org-virtual-routes
    — 理解虚拟文件路由

Data Loading (Prefix: 
load-
)

数据加载（前缀：
load-
）

  • load-use-loaders
    — Use route loaders for data fetching
  • load-loader-deps
    — Define loaderDeps for cache control
  • load-ensure-query-data
    — Use ensureQueryData with TanStack Query
  • load-deferred-data
    — Split critical and non-critical data
  • load-error-handling
    — Handle loader errors appropriately
  • load-parallel
    — Leverage parallel route loading
  • load-use-loaders
    — 使用路由加载器进行数据获取
  • load-loader-deps
    — 定义 loaderDeps 以控制缓存
  • load-ensure-query-data
    — 结合 TanStack Query 使用 ensureQueryData
  • load-deferred-data
    — 拆分关键与非关键数据
  • load-error-handling
    — 正确处理加载器错误
  • load-parallel
    — 利用并行路由加载

Search Params (Prefix: 
search-
)

搜索参数（前缀：
search-
）

  • search-validation
    — Always validate search params
  • search-type-inheritance
    — Leverage parent search param types
  • search-middleware
    — Use search param middleware
  • search-defaults
    — Provide sensible defaults
  • search-custom-serializer
    — Configure custom search param serializers
  • search-validation
    — 始终验证搜索参数
  • search-type-inheritance
    — 利用父级搜索参数类型
  • search-middleware
    — 使用搜索参数中间件
  • search-defaults
    — 提供合理的默认值
  • search-custom-serializer
    — 配置自定义搜索参数序列化器

Error Handling (Prefix: 
err-
)

错误处理（前缀：
err-
）

  • err-not-found
    — Handle not-found routes properly
  • err-not-found
    — 正确处理未找到的路由

Navigation (Prefix: 
nav-
)

导航（前缀：
nav-
）

  • nav-link-component
    — Prefer Link component for navigation
  • nav-active-states
    — Configure active link states
  • nav-use-navigate
    — Use useNavigate for programmatic navigation
  • nav-relative-paths
    — Understand relative path navigation
  • nav-route-masks
    — Use route masks for modal URLs
  • nav-link-component
    — 优先使用 Link 组件进行导航
  • nav-active-states
    — 配置活动链接状态
  • nav-use-navigate
    — 使用 useNavigate 进行编程式导航
  • nav-relative-paths
    — 理解相对路径导航
  • nav-route-masks
    — 使用路由掩码实现模态框 URL

Code Splitting (Prefix: 
split-
)

代码分割（前缀：
split-
）

  • split-lazy-routes
    — Use .lazy.tsx for code splitting
  • split-critical-path
    — Keep critical config in main route file
  • split-auto-splitting
    — Enable autoCodeSplitting when possible
  • split-lazy-routes
    — 使用 .lazy.tsx 进行代码分割
  • split-critical-path
    — 将关键配置保留在主路由文件中
  • split-auto-splitting
    — 尽可能启用 autoCodeSplitting

Preloading (Prefix: 
preload-
)

预加载（前缀：
preload-
）

  • preload-intent
    — Enable intent-based preloading
  • preload-stale-time
    — Configure preload stale time
  • preload-manual
    — Use manual preloading strategically
  • preload-intent
    — 启用基于意图的预加载
  • preload-stale-time
    — 配置预加载过期时间
  • preload-manual
    — 策略性地使用手动预加载

Route Context (Prefix: 
ctx-
)

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

  • ctx-root-context
    — Define context at root route
  • ctx-before-load
    — Extend context in beforeLoad
  • ctx-dependency-injection
    — Use context for dependency injection
  • ctx-root-context
    — 在根路由定义上下文
  • ctx-before-load
    — 在 beforeLoad 中扩展上下文
  • ctx-dependency-injection
    — 使用上下文进行依赖注入

How to Use

使用方法

Each rule file in the 
rules/
directory contains:
  1. Explanation — Why this pattern matters
  2. Bad Example — Anti-pattern to avoid
  3. Good Example — Recommended implementation
  4. Context — When to apply or skip this rule
rules/
目录中的每个规则文件包含：
  1. 说明 — 该模式的重要性
  2. 反面示例 — 需要避免的反模式
  3. 正面示例 — 推荐的实现方式
  4. 适用场景 — 何时应用或跳过该规则

Full Reference

完整参考

See individual rule files in 
rules/
directory for detailed guidance and code examples.
请查看 
rules/
目录中的单个规则文件，获取详细指南与代码示例。