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:

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