AgentSkillsCN

tanstack-router-best-practices

掌握TanStack Router在类型安全路由、数据加载、查询参数与导航方面的最佳实践。在构建具有复杂路由需求的React应用时启用此技能。

SKILL.md
--- frontmatter
name: tanstack-router-best-practices
description: TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.

TanStack Router Best Practices

Comprehensive guidelines for implementing TanStack Router patterns in React applications. These rules optimize type safety, data loading, navigation, and code organization.

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

Rule Categories by Priority

PriorityCategoryRulesImpact
CRITICALType Safety2 rulesPrevents runtime errors and enables refactoring
CRITICALRoute Organization1 ruleEnsures maintainable route structure
HIGHRouter Config1 ruleGlobal router defaults
HIGHData Loading3 rulesOptimizes data fetching and caching
HIGHSearch Params2 rulesEnables type-safe URL state
HIGHError Handling1 ruleHandles 404 and errors gracefully
MEDIUMNavigation2 rulesImproves UX and accessibility
MEDIUMCode Splitting1 ruleReduces bundle size
MEDIUMPreloading1 ruleImproves perceived performance
LOWRoute Context1 ruleEnables dependency injection

Quick Reference

Type Safety (Prefix: ts-)

  • •ts-register-router — Register router type for global inference
  • •ts-use-from-param — Use from parameter for type narrowing

Router Config (Prefix: router-)

  • •router-default-options — Configure router defaults (scrollRestoration, defaultErrorComponent, etc.)

Route Organization (Prefix: org-)

  • •org-virtual-routes — Understand virtual file routes

Data Loading (Prefix: load-)

  • •load-use-loaders — Use route loaders for data fetching
  • •load-ensure-query-data — Use ensureQueryData with TanStack Query
  • •load-parallel — Leverage parallel route loading

When TanStack Query is also in use, follow tanstack-integration/rules/precedence-query-first.md so Query remains the single server-state cache authority.

Search Params (Prefix: search-)

  • •search-validation — Always validate search params
  • •search-custom-serializer — Configure custom search param serializers

Error Handling (Prefix: err-)

  • •err-not-found — Handle not-found routes properly

Navigation (Prefix: nav-)

  • •nav-link-component — Prefer Link component for navigation
  • •nav-route-masks — Use route masks for modal URLs

Code Splitting (Prefix: split-)

  • •split-lazy-routes — Use .lazy.tsx for code splitting

Preloading (Prefix: preload-)

  • •preload-intent — Enable intent-based preloading

Route Context (Prefix: ctx-)

  • •ctx-root-context — Define context at root route

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

Full Reference

See individual rule files in rules/ directory for detailed guidance and code examples.