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
| Priority | Category | Rules | Impact |
|---|---|---|---|
| CRITICAL | Type Safety | 4 rules | Prevents runtime errors and enables refactoring |
| CRITICAL | Route Organization | 5 rules | Ensures maintainable route structure |
| HIGH | Router Config | 1 rule | Global router defaults |
| HIGH | Data Loading | 6 rules | Optimizes data fetching and caching |
| HIGH | Search Params | 5 rules | Enables type-safe URL state |
| HIGH | Error Handling | 1 rule | Handles 404 and errors gracefully |
| MEDIUM | Navigation | 5 rules | Improves UX and accessibility |
| MEDIUM | Code Splitting | 3 rules | Reduces bundle size |
| MEDIUM | Preloading | 3 rules | Improves perceived performance |
| LOW | Route Context | 3 rules | Enables dependency injection |
Quick Reference
Type Safety (Prefix: ts-)
- •
ts-register-router— Register router type for global inference - •
ts-use-from-param— Usefromparameter 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:
- •Explanation — Why this pattern matters
- •Bad Example — Anti-pattern to avoid
- •Good Example — Recommended implementation
- •Context — When to apply or skip this rule
Full Reference
See individual rule files in rules/ directory for detailed guidance and code examples.