TanStack Router Best Practices

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

rules/

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

rules/