cenjie/tanstack-router-best-practices

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