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

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.