tanstack-router-best-practices
deckardger/tanstack-agent-skills
Type-safe routing patterns and best practices for TanStack Router in React applications.
What is tanstack-router-best-practices?
Comprehensive guidelines for implementing TanStack Router in React apps, covering type safety, data loading, search parameters, navigation, and code organization. Use when building applications with complex routing needs or setting up new routes and layouts.
- Provides 38 categorized rules for type-safe routing and route organization
- Guides data loading patterns with TanStack Query integration
- Enables type-safe search parameter handling and validation
- Covers error handling, code splitting, and preloading strategies
- Includes navigation patterns and active link state management
- Supports route context and dependency injection patterns
How to install tanstack-router-best-practices
npx skills add https://github.com/deckardger/tanstack-agent-skills --skill tanstack-router-best-practicesHow to use tanstack-router-best-practices
- 1.Review the rule categories by priority (Critical, High, Medium, Low) to understand focus areas
- 2.Consult individual rule files in the rules/ directory for detailed explanations and code examples
- 3.Apply type safety rules (ts-*) first to enable refactoring and prevent runtime errors
- 4.Configure router defaults and route organization (router-*, org-*) for your project structure
- 5.Implement data loading patterns (load-*) with TanStack Query integration
- 6.Add search parameter validation (search-*) and error handling (err-*) as needed
- 7.Optimize with code splitting (split-*) and preloading (preload-*) strategies
Use cases
- Setting up application routing architecture in a new React project
- Implementing complex multi-level route hierarchies with shared layouts
- Configuring data loaders and integrating with TanStack Query for optimized fetching
- Handling search parameters with type safety and validation
- Refactoring existing navigation patterns to follow best practices
- React developers building applications with complex routing
- Teams standardizing TanStack Router patterns across projects
- Developers integrating TanStack Router with TanStack Query
- Frontend architects designing scalable routing systems
tanstack-router-best-practices FAQ
Type Safety (4 rules) and Route Organization (5 rules) are marked critical. These prevent runtime errors, enable safe refactoring, and ensure maintainable route structure.
The skill includes patterns for using queryOptions in loaders, ensureQueryData for data fetching, and loaderDeps for cache control to optimize data loading with TanStack Query.
Yes, the skill includes org-file-based-routing rule that prefers file-based routing conventions and explains virtual file routes.
The search-* rules cover validation, type inheritance from parent routes, middleware, defaults, and custom serializers for type-safe URL state management.
The org-index-routes rule explains that index routes render at their path while layout routes provide shared structure; the skill clarifies when to use each pattern.
Full instructions (SKILL.md)
Source of truth, from deckardger/tanstack-agent-skills.
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 inferencets-use-from-param— Usefromparameter for type narrowingts-route-context-typing— Type route context with createRootRouteWithContextts-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 conventionsorg-route-tree-structure— Follow hierarchical route tree patternsorg-pathless-layouts— Use pathless routes for shared layoutsorg-index-routes— Understand index vs layout routesorg-virtual-routes— Understand virtual file routes
Data Loading (Prefix: load-)
load-use-loaders— Use route loaders for data fetchingload-loader-deps— Define loaderDeps for cache controlload-ensure-query-data— Use ensureQueryData with TanStack Queryload-deferred-data— Split critical and non-critical dataload-error-handling— Handle loader errors appropriatelyload-parallel— Leverage parallel route loading
Search Params (Prefix: search-)
search-validation— Always validate search paramssearch-type-inheritance— Leverage parent search param typessearch-middleware— Use search param middlewaresearch-defaults— Provide sensible defaultssearch-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 navigationnav-active-states— Configure active link statesnav-use-navigate— Use useNavigate for programmatic navigationnav-relative-paths— Understand relative path navigationnav-route-masks— Use route masks for modal URLs
Code Splitting (Prefix: split-)
split-lazy-routes— Use .lazy.tsx for code splittingsplit-critical-path— Keep critical config in main route filesplit-auto-splitting— Enable autoCodeSplitting when possible
Preloading (Prefix: preload-)
preload-intent— Enable intent-based preloadingpreload-stale-time— Configure preload stale timepreload-manual— Use manual preloading strategically
Route Context (Prefix: ctx-)
ctx-root-context— Define context at root routectx-before-load— Extend context in beforeLoadctx-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.
Related skills
More from deckardger/tanstack-agent-skills and the wider catalog.
tanstack-start-best-practices
TanStack Start best practices for full-stack React: server functions, middleware, SSR, auth, and deployment.
tanstack-integration-best-practices
Best practices for coordinating TanStack Query, Router, and Start in full-stack applications.
tanstack-query-best-practices
TanStack Query best practices for optimized data fetching, caching, and server state management in React.
mies
Ruthless reduction and exacting craft for user-facing interfaces, applying Mies van der Rohe restraint and anti-generic design discipline.
wonda-cli
Terminal toolkit for generating media and automating social research across LinkedIn, Reddit, and X/Twitter.
astro-framework
Astro framework specialist for fast, content-driven websites with islands architecture and hybrid rendering.