tanstack-router-best-practices

Original：🇺🇸 English
Not Translated

TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.

3installs
Sourcepedronauck/skills
Added on

NPX Install

npx skill4agent add pedronauck/skills tanstack-router-best-practices

SKILL.md Content

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 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

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
  • ts-route-context-typing
    — Type route context with createRootRouteWithContext
  • ts-query-options-loader
    — Use queryOptions in loaders for type inference

Router Config (Prefix: 
router-
)

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

Route Organization (Prefix: 
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

Data Loading (Prefix: 
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

Search Params (Prefix: 
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

Error Handling (Prefix: 
err-
)

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

Navigation (Prefix: 
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

Code Splitting (Prefix: 
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

Preloading (Prefix: 
preload-
)

  • preload-intent
    — Enable intent-based preloading
  • preload-stale-time
    — Configure preload stale time
  • preload-manual
    — Use manual preloading strategically

Route Context (Prefix: 
ctx-
)

  • ctx-root-context
    — Define context at root route
  • ctx-before-load
    — Extend context in beforeLoad
  • ctx-dependency-injection
    — Use context for 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

Full Reference

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