playbooks

home / skills / deckardger / tanstack-agent-skills / tanstack-router

tanstack-router skill

/skills/tanstack-router

This skill helps you apply TanStack Router best practices for type-safe routing, data loading, and navigation in complex React apps.

npx playbooks add skill deckardger/tanstack-agent-skills --skill tanstack-router

Review the files below or copy the command above to add this skill to your agents.

Files (16)
SKILL.md
4.5 KB
---
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

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

Overview

This skill provides best practices for using TanStack Router in React applications to achieve type-safe routing, reliable data loading, and predictable navigation. It consolidates guidance on route organization, search param handling, code splitting, and integration with TanStack Query. Activate this skill when you want maintainable, performant routing for complex app flows.

How this skill works

The skill inspects routing patterns and recommends concrete rules for type registration, route tree structure, loader configuration, and search param typing. It highlights critical conventions (type safety, route organization) and practical patterns for loaders, preloading, error handling, and navigation. Each rule includes rationale, anti-patterns, and recommended implementations to apply during development or refactoring.

When to use it

  • Setting up or refactoring application routing and layouts
  • Implementing type-safe route params, contexts, and search params
  • Configuring data loaders, caching, and TanStack Query integration
  • Adding code splitting, lazy routes, and preloading strategies
  • Designing navigation UX, link states, and modal/relative routes

Best practices

  • Register router types globally to enable compile-time inference and safer refactors
  • Organize routes in a hierarchical, file-based structure with pathless layouts for shared UI
  • Use route loaders with loaderDeps and ensureQueryData to coordinate server and client cache
  • Validate and type search params, inherit parent param types, and provide sensible defaults
  • Prefer Link for declarative navigation, use useNavigate for programmatic flows, and handle relative paths explicitly
  • Split non-critical route UI with .lazy routes and keep critical routing config in the main route file

Example use cases

  • Building a multi-layout dashboard with nested, type-safe routes and shared contexts
  • Migrating imperative fetch logic into route loaders that integrate with TanStack Query
  • Implementing paginated listings that persist sort and filters via typed search params
  • Improving initial load performance by lazy-loading feature routes and intent-based preloads
  • Handling 404 and loader errors with a centralized error component and per-route fallbacks

FAQ

How do I ensure route params are type-safe across the app?

Register the router types at app initialization, type route contexts with createRootRouteWithContext, and prefer typed utilities like useFromParam and queryOptions in loaders.

When should I use deferred loaders vs ensureQueryData?

Use deferred loaders to split critical and non-critical data on the route. Use ensureQueryData when you want to hydrate or reuse existing TanStack Query cache for immediate rendering.