Covers the full SOLID module structure (modules/cores/lib/router/, feature modules with interfaces//queries//components/), migration from React Router (useParams()→Route.useParams(), loader→loader option), and error boundaries/404 handling. Does not cover state management (react-state) or forms (react-forms) — those are separate skills; for Next.js routing use the App Router (nextjs-16), not this skill.
TanStack Router
100% type-safe router for React with file-based routing, loaders, search params validation, and deep TanStack Query integration.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Analyze existing routes and navigation patterns
- fuse-ai-pilot:research-expert - Verify latest TanStack Router docs via Context7/Exa
- mcp__context7__query-docs - Check file-based routing and type-safe patterns
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
Why TanStack Router?
TanStack Router is the recommended choice for React SPAs requiring type-safe routing with search params validation.
| Feature |
TanStack Router |
React Router v7 |
| Type Safety |
Full inference |
Auto-generated |
| File-based Routing |
Built-in |
Framework mode |
| Search Params Validation |
Zod, Valibot |
Manual |
| Preloading |
Intent, render |
Limited |
| TanStack Query Integration |
Native |
Manual |
When to Use
- React SPA with Vite, Webpack, or Rspack → See installation.md
- Type-safe routing required → See typescript.md
- Search params validation needed → See search-params.md
- TanStack Query for data fetching → See tanstack-query.md
- NOT Next.js (use App Router instead)
Critical Rules
- ALWAYS use file-based routing - Auto-generated type safety → file-based-routing.md
- ALWAYS validate search params - Use Zod schemas with
zodValidator → search-params.md
- ALWAYS use Route.useLoaderData() - Not global useLoaderData → hooks.md
- ALWAYS register router types -
declare module '@tanstack/react-router' → typescript.md
- PREFER loaders over useEffect - Data fetching before render → loaders.md
- INTEGRATE TanStack Query - For caching, mutations, optimistic updates → tanstack-query.md
- FOLLOW SOLID architecture - Modules, interfaces, file size limits → solid-react skill
Quick Reference: What to Read
Starting a new project
- Read installation.md for configuration
- Copy template basic-setup.md as base
Creating a feature module (posts, users, etc.)
- Follow architecture in templates/feature-module.md
- Use patterns from tanstack-query.md for queries
Implementing authentication
- Read auth-guards.md for concepts
- Copy template auth-protected-routes.md
Creating a page with filters/search
- Read search-params.md for Zod validation
- Copy template search-filters.md
Creating a dashboard with nested layouts
- Read nested-routes.md for concepts
- Copy template dashboard-layout.md
Project Structure (SOLID Architecture)
Recommended structure following SOLID principles from solid-react skill.
src/
├── modules/
│ ├── cores/ # Shared between features
│ │ ├── lib/
│ │ │ ├── router/router.ts # Router configuration
│ │ │ └── query/client.ts # QueryClient configuration
│ │ ├── components/layouts/ # Shared layouts
│ │ └── interfaces/ # Shared types
│ └── [feature]/ # Feature module
│ ├── src/
│ │ ├── interfaces/ # Module types
│ │ ├── queries/ # TanStack Query options
│ │ └── components/ # Module components
│ └── index.ts # Public exports
├── routes/ # Route definitions ONLY
│ ├── __root.tsx
│ └── [feature]/
└── routeTree.gen.ts # Auto-generated (DO NOT MODIFY)
Full template: templates/basic-setup.md
Reference Guide
Concepts (references/) - Conceptual Documentation
| Topic |
Reference |
When to consult |
| Setup |
installation.md |
Vite/Webpack config, React Router migration |
| File Routing |
file-based-routing.md |
Naming conventions, routes/ structure |
| URL Params |
route-params.md |
Dynamic routes $postId, parsing |
| Search Params |
search-params.md |
Zod validation, URL filters, pagination |
| Data Loading |
loaders.md |
Loaders, prefetch, TanStack Query integration |
| Navigation |
navigation.md |
Link, useNavigate, redirects |
| Context |
route-context.md |
Dependency injection, QueryClient, user |
| Layouts |
nested-routes.md |
Nested layouts, Outlet, pathless routes |
| Errors |
error-handling.md |
Error boundaries, 404, pending states |
| Lazy Loading |
code-splitting.md |
Code splitting, bundle optimization |
| Preloading |
preloading.md |
Preload intent/render, prefetch |
| Auth |
auth-guards.md |
Protected routes, RBAC, login redirect |
| TanStack Query |
tanstack-query.md |
queryOptions, mutations, cache |
| SSR |
ssr.md |
Server-side rendering, TanStack Start |
| TypeScript |
typescript.md |
Type registration, inference, type safety |
| DevTools |
devtools.md |
Router DevTools setup |
| Hooks API |
hooks.md |
useParams, useSearch, useNavigate, etc. |
| Components |
components.md |
Link, Outlet, Navigate, RouterProvider |
Templates (references/templates/) - Complete Copy-Paste Ready Code
| Template |
When to use |
| basic-setup.md |
Start a new project with SOLID architecture |
| feature-module.md |
Create a complete feature module (interfaces, queries, components) |
| auth-protected-routes.md |
Implement login, protected routes, RBAC |
| search-filters.md |
Page with URL filters, pagination, sorting |
| dashboard-layout.md |
Dashboard with sidebar, tabs, nested layouts |
Core Patterns
1. Root Route with Context
Router context configuration for dependency injection.
// src/routes/__root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
component: RootComponent,
})
Details: route-context.md
Template: templates/basic-setup.md
2. File Route with Loader and TanStack Query
Recommended pattern for data loading with cache.
// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
loader: ({ context: { queryClient }, params }) =>
queryClient.ensureQueryData(postQueryOptions(params.postId)),
component: PostPage,
})
Details: loaders.md, tanstack-query.md
Template: templates/feature-module.md
3. Search Params with Zod Validation
Type-safe filters and pagination via URL.
// src/routes/posts/index.tsx
const searchSchema = z.object({
page: z.number().min(1).default(1),
sort: z.enum(['newest', 'oldest']).default('newest'),
})
export const Route = createFileRoute('/posts/')({
validateSearch: zodValidator(searchSchema),
})
Details: search-params.md
Template: templates/search-filters.md
4. Protected Routes
Authentication guard with redirect.
// src/routes/_authenticated/_authenticated.tsx
export const Route = createFileRoute('/_authenticated')({
beforeLoad: ({ context, location }) => {
if (!context.user) {
throw redirect({ to: '/login', search: { redirect: location.href } })
}
},
})
Details: auth-guards.md
Template: templates/auth-protected-routes.md
5. Nested Layouts with Outlet
Nested layouts for dashboards.
// src/routes/_dashboard/_dashboard.tsx
export const Route = createFileRoute('/_dashboard')({
component: () => (
<DashboardLayout>
<Outlet />
</DashboardLayout>
),
})
Details: nested-routes.md
Template: templates/dashboard-layout.md
Best Practices
Do's
| Pattern |
Reference |
Use Route API (Route.useParams()) |
hooks.md |
| Validate search params with Zod |
search-params.md |
Use ensureQueryData in loaders |
tanstack-query.md |
| Preload on intent for links |
preloading.md |
Separate interfaces in interfaces/ |
solid-react skill |
Don'ts
| Anti-pattern |
Why |
Alternative |
useLoaderData() without from |
Not type-safe |
Route.useLoaderData() |
useEffect for fetch |
Not optimal |
Use loaders |
| Mutate search params |
Immutability |
navigate({ search: {...} }) |
| Skip error boundaries |
Degraded UX |
Add errorComponent |
| Interfaces in components |
Coupling |
interfaces/ folder |
Migration from React Router
See installation.md for complete migration guide.
| React Router |
TanStack Router |
useParams() |
Route.useParams() |
useSearchParams() |
Route.useSearch() |
useLoaderData() |
Route.useLoaderData() |
loader function |
loader option |
action function |
TanStack Query mutations |
Version History
- v1.x - Frequent releases (incremental versioning)
- Key milestones: Head/meta tags, Search params middlewares, Zod adapter
1---2name: react-tanstack-router3description: Use when implementing routing in a React app (NOT Next.js) with TanStack Router — file-based routes, loaders, search params.4versions:5 tanstack-router: "1.x (latest)"6 react: 197 zod: 3.x8user-invocable: true9references: references/installation.md, references/file-based-routing.md, references/route-params.md, references/search-params.md, references/loaders.md, references/navigation.md, references/route-context.md, references/nested-routes.md, references/error-handling.md, references/code-splitting.md, references/preloading.md, references/auth-guards.md, references/tanstack-query.md, references/ssr.md, references/typescript.md, references/devtools.md, references/hooks.md, references/components.md, references/templates/basic-setup.md, references/templates/feature-module.md, references/templates/auth-protected-routes.md, references/templates/search-filters.md, references/templates/dashboard-layout.md10related-skills: react-forms, react-state, react-19, solid-react11metadata:12 source: https://skillmd.com/skills/fusengine/react-tanstack-router13---1415<objective>16Implements TanStack Router for React SPAs (Vite/Webpack/Rspack, not Next.js): file-based routing with auto-generated type safety, dynamic route params (`$postId`), search-params validation with Zod/Valibot, loaders (`Route.useLoaderData()`) integrated with TanStack Query (`ensureQueryData`), nested layouts with `Outlet`, route context for dependency injection, protected routes via `beforeLoad` guards, and preloading on intent/render.1718Covers the full SOLID module structure (`modules/cores/lib/router/`, feature modules with `interfaces/`/`queries/`/`components/`), migration from React Router (`useParams()`→`Route.useParams()`, `loader`→`loader` option), and error boundaries/404 handling. Does not cover state management (react-state) or forms (react-forms) — those are separate skills; for Next.js routing use the App Router (nextjs-16), not this skill.19</objective>2021# TanStack Router2223100% type-safe router for React with file-based routing, loaders, search params validation, and deep TanStack Query integration.2425## Agent Workflow (MANDATORY)2627Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:28291. **fuse-ai-pilot:explore-codebase** - Analyze existing routes and navigation patterns302. **fuse-ai-pilot:research-expert** - Verify latest TanStack Router docs via Context7/Exa313. **mcp__context7__query-docs** - Check file-based routing and type-safe patterns3233After implementation, run **fuse-ai-pilot:sniper** for validation.3435---3637## Overview3839### Why TanStack Router?4041TanStack Router is the recommended choice for React SPAs requiring type-safe routing with search params validation.4243| Feature | TanStack Router | React Router v7 |44|---------|----------------|-----------------|45| Type Safety | Full inference | Auto-generated |46| File-based Routing | Built-in | Framework mode |47| Search Params Validation | Zod, Valibot | Manual |48| Preloading | Intent, render | Limited |49| TanStack Query Integration | Native | Manual |5051### When to Use5253- **React SPA** with Vite, Webpack, or Rspack → See [installation.md](references/installation.md)54- **Type-safe routing** required → See [typescript.md](references/typescript.md)55- **Search params validation** needed → See [search-params.md](references/search-params.md)56- **TanStack Query** for data fetching → See [tanstack-query.md](references/tanstack-query.md)57- **NOT Next.js** (use App Router instead)5859---6061## Critical Rules62631. **ALWAYS use file-based routing** - Auto-generated type safety → [file-based-routing.md](references/file-based-routing.md)642. **ALWAYS validate search params** - Use Zod schemas with `zodValidator` → [search-params.md](references/search-params.md)653. **ALWAYS use Route.useLoaderData()** - Not global useLoaderData → [hooks.md](references/hooks.md)664. **ALWAYS register router types** - `declare module '@tanstack/react-router'` → [typescript.md](references/typescript.md)675. **PREFER loaders over useEffect** - Data fetching before render → [loaders.md](references/loaders.md)686. **INTEGRATE TanStack Query** - For caching, mutations, optimistic updates → [tanstack-query.md](references/tanstack-query.md)697. **FOLLOW SOLID architecture** - Modules, interfaces, file size limits → [solid-react skill](../solid-react/SKILL.md)7071---7273## Quick Reference: What to Read7475### Starting a new project761. Read [installation.md](references/installation.md) for configuration772. Copy template [basic-setup.md](references/templates/basic-setup.md) as base7879### Creating a feature module (posts, users, etc.)801. Follow architecture in [templates/feature-module.md](references/templates/feature-module.md)812. Use patterns from [tanstack-query.md](references/tanstack-query.md) for queries8283### Implementing authentication841. Read [auth-guards.md](references/auth-guards.md) for concepts852. Copy template [auth-protected-routes.md](references/templates/auth-protected-routes.md)8687### Creating a page with filters/search881. Read [search-params.md](references/search-params.md) for Zod validation892. Copy template [search-filters.md](references/templates/search-filters.md)9091### Creating a dashboard with nested layouts921. Read [nested-routes.md](references/nested-routes.md) for concepts932. Copy template [dashboard-layout.md](references/templates/dashboard-layout.md)9495---9697## Project Structure (SOLID Architecture)9899Recommended structure following SOLID principles from `solid-react` skill.100101```text102src/103├── modules/104│ ├── cores/ # Shared between features105│ │ ├── lib/106│ │ │ ├── router/router.ts # Router configuration107│ │ │ └── query/client.ts # QueryClient configuration108│ │ ├── components/layouts/ # Shared layouts109│ │ └── interfaces/ # Shared types110│ └── [feature]/ # Feature module111│ ├── src/112│ │ ├── interfaces/ # Module types113│ │ ├── queries/ # TanStack Query options114│ │ └── components/ # Module components115│ └── index.ts # Public exports116├── routes/ # Route definitions ONLY117│ ├── __root.tsx118│ └── [feature]/119└── routeTree.gen.ts # Auto-generated (DO NOT MODIFY)120```121122> **Full template**: [templates/basic-setup.md](references/templates/basic-setup.md)123124---125126## Reference Guide127128### Concepts (references/) - Conceptual Documentation129130| Topic | Reference | When to consult |131|-------|-----------|-----------------|132| **Setup** | [installation.md](references/installation.md) | Vite/Webpack config, React Router migration |133| **File Routing** | [file-based-routing.md](references/file-based-routing.md) | Naming conventions, routes/ structure |134| **URL Params** | [route-params.md](references/route-params.md) | Dynamic routes `$postId`, parsing |135| **Search Params** | [search-params.md](references/search-params.md) | Zod validation, URL filters, pagination |136| **Data Loading** | [loaders.md](references/loaders.md) | Loaders, prefetch, TanStack Query integration |137| **Navigation** | [navigation.md](references/navigation.md) | Link, useNavigate, redirects |138| **Context** | [route-context.md](references/route-context.md) | Dependency injection, QueryClient, user |139| **Layouts** | [nested-routes.md](references/nested-routes.md) | Nested layouts, Outlet, pathless routes |140| **Errors** | [error-handling.md](references/error-handling.md) | Error boundaries, 404, pending states |141| **Lazy Loading** | [code-splitting.md](references/code-splitting.md) | Code splitting, bundle optimization |142| **Preloading** | [preloading.md](references/preloading.md) | Preload intent/render, prefetch |143| **Auth** | [auth-guards.md](references/auth-guards.md) | Protected routes, RBAC, login redirect |144| **TanStack Query** | [tanstack-query.md](references/tanstack-query.md) | queryOptions, mutations, cache |145| **SSR** | [ssr.md](references/ssr.md) | Server-side rendering, TanStack Start |146| **TypeScript** | [typescript.md](references/typescript.md) | Type registration, inference, type safety |147| **DevTools** | [devtools.md](references/devtools.md) | Router DevTools setup |148| **Hooks API** | [hooks.md](references/hooks.md) | useParams, useSearch, useNavigate, etc. |149| **Components** | [components.md](references/components.md) | Link, Outlet, Navigate, RouterProvider |150151### Templates (references/templates/) - Complete Copy-Paste Ready Code152153| Template | When to use |154|----------|-------------|155| [**basic-setup.md**](references/templates/basic-setup.md) | Start a new project with SOLID architecture |156| [**feature-module.md**](references/templates/feature-module.md) | Create a complete feature module (interfaces, queries, components) |157| [**auth-protected-routes.md**](references/templates/auth-protected-routes.md) | Implement login, protected routes, RBAC |158| [**search-filters.md**](references/templates/search-filters.md) | Page with URL filters, pagination, sorting |159| [**dashboard-layout.md**](references/templates/dashboard-layout.md) | Dashboard with sidebar, tabs, nested layouts |160161---162163## Core Patterns164165### 1. Root Route with Context166167Router context configuration for dependency injection.168169```typescript170// src/routes/__root.tsx171export const Route = createRootRouteWithContext<RouterContext>()({172 component: RootComponent,173})174```175176> **Details**: [route-context.md](references/route-context.md)177> **Template**: [templates/basic-setup.md](references/templates/basic-setup.md)178179### 2. File Route with Loader and TanStack Query180181Recommended pattern for data loading with cache.182183```typescript184// src/routes/posts/$postId.tsx185export const Route = createFileRoute('/posts/$postId')({186 loader: ({ context: { queryClient }, params }) =>187 queryClient.ensureQueryData(postQueryOptions(params.postId)),188 component: PostPage,189})190```191192> **Details**: [loaders.md](references/loaders.md), [tanstack-query.md](references/tanstack-query.md)193> **Template**: [templates/feature-module.md](references/templates/feature-module.md)194195### 3. Search Params with Zod Validation196197Type-safe filters and pagination via URL.198199```typescript200// src/routes/posts/index.tsx201const searchSchema = z.object({202 page: z.number().min(1).default(1),203 sort: z.enum(['newest', 'oldest']).default('newest'),204})205206export const Route = createFileRoute('/posts/')({207 validateSearch: zodValidator(searchSchema),208})209```210211> **Details**: [search-params.md](references/search-params.md)212> **Template**: [templates/search-filters.md](references/templates/search-filters.md)213214### 4. Protected Routes215216Authentication guard with redirect.217218```typescript219// src/routes/_authenticated/_authenticated.tsx220export const Route = createFileRoute('/_authenticated')({221 beforeLoad: ({ context, location }) => {222 if (!context.user) {223 throw redirect({ to: '/login', search: { redirect: location.href } })224 }225 },226})227```228229> **Details**: [auth-guards.md](references/auth-guards.md)230> **Template**: [templates/auth-protected-routes.md](references/templates/auth-protected-routes.md)231232### 5. Nested Layouts with Outlet233234Nested layouts for dashboards.235236```typescript237// src/routes/_dashboard/_dashboard.tsx238export const Route = createFileRoute('/_dashboard')({239 component: () => (240 <DashboardLayout>241 <Outlet />242 </DashboardLayout>243 ),244})245```246247> **Details**: [nested-routes.md](references/nested-routes.md)248> **Template**: [templates/dashboard-layout.md](references/templates/dashboard-layout.md)249250---251252## Best Practices253254### Do's255256| Pattern | Reference |257|---------|-----------|258| Use Route API (`Route.useParams()`) | [hooks.md](references/hooks.md) |259| Validate search params with Zod | [search-params.md](references/search-params.md) |260| Use `ensureQueryData` in loaders | [tanstack-query.md](references/tanstack-query.md) |261| Preload on intent for links | [preloading.md](references/preloading.md) |262| Separate interfaces in `interfaces/` | [solid-react skill](../solid-react/SKILL.md) |263264### Don'ts265266| Anti-pattern | Why | Alternative |267|--------------|-----|-------------|268| `useLoaderData()` without `from` | Not type-safe | `Route.useLoaderData()` |269| `useEffect` for fetch | Not optimal | Use loaders |270| Mutate search params | Immutability | `navigate({ search: {...} })` |271| Skip error boundaries | Degraded UX | Add `errorComponent` |272| Interfaces in components | Coupling | `interfaces/` folder |273274---275276## Migration from React Router277278See [installation.md](references/installation.md) for complete migration guide.279280| React Router | TanStack Router |281|--------------|-----------------|282| `useParams()` | `Route.useParams()` |283| `useSearchParams()` | `Route.useSearch()` |284| `useLoaderData()` | `Route.useLoaderData()` |285| `loader` function | `loader` option |286| `action` function | TanStack Query mutations |287288---289290## Version History291292- **v1.x** - Frequent releases (incremental versioning)293- Key milestones: Head/meta tags, Search params middlewares, Zod adapter