/react-tanstack-router

name: react-tanstack-router
description: Use when implementing routing in a React app (NOT Next.js) with TanStack Router — file-based routes, loaders, search params.
versions:
  tanstack-router: "1.x (latest)"
  react: 19
  zod: 4.x
user-invocable: true
references: 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.md
related-skills: react-forms, react-state, react-19, solid-react

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

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

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`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing routes and navigation patterns 2. **fuse-ai-pilot:research-expert** - Verify latest TanStack Router docs via Context7/Exa 3. **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](references/installation.md)
• **Type-safe routing** required → See [typescript.md](references/typescript.md)
• **Search params validation** needed → See [search-params.md](references/search-params.md)
• **TanStack Query** for data fetching → See [tanstack-query.md](references/tanstack-query.md)
• **NOT Next.js** (use App Router instead)

---

Critical Rules

1. **ALWAYS use file-based routing** - Auto-generated type safety → [file-based-routing.md](references/file-based-routing.md) 2. **ALWAYS validate search params** - Pass the Zod v4 schema directly to `validateSearch` (`zodValidator` only for Zod v3) → [search-params.md](references/search-params.md) 3. **ALWAYS use Route.useLoaderData()** - Not global useLoaderData → [hooks.md](references/hooks.md) 4. **ALWAYS register router types** - `declare module '@tanstack/react-router'` → [typescript.md](references/typescript.md) 5. **PREFER loaders over useEffect** - Data fetching before render → [loaders.md](references/loaders.md) 6. **INTEGRATE TanStack Query** - For caching, mutations, optimistic updates → [tanstack-query.md](references/tanstack-query.md) 7. **FOLLOW SOLID architecture** - Modules, interfaces, file size limits → [solid-react skill](../solid-react/SKILL.md)

---

Quick Reference: What to Read

Starting a new project

1. Read [installation.md](references/installation.md) for configuration 2. Copy template [basic-setup.md](references/templates/basic-setup.md) as base

Creating a feature module (posts, users, etc.)

1. Follow architecture in [templates/feature-module.md](references/templates/feature-module.md) 2. Use patterns from [tanstack-query.md](references/tanstack-query.md) for queries

Implementing authentication

1. Read [auth-guards.md](references/auth-guards.md) for concepts 2. Copy template [auth-protected-routes.md](references/templates/auth-protected-routes.md)

Creating a page with filters/search

1. Read [search-params.md](references/search-params.md) for Zod validation 2. Copy template [search-filters.md](references/templates/search-filters.md)

Creating a dashboard with nested layouts

1. Read [nested-routes.md](references/nested-routes.md) for concepts 2. Copy template [dashboard-layout.md](references/templates/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/            # TanS