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, use TeamCreate to spawn 3 agents:

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

react-tanstack-router