/web-routing-tanstack-router

name: web-routing-tanstack-router
description: Type-safe client-side routing for React with file-based routes, search params validation, loaders, and code splitting

TanStack Router Patterns

> **Quick Guide:** TanStack Router provides fully type-safe client-side routing for React. Use file-based routing with `@tanstack/router-plugin` for automatic route tree generation. Define search params with Zod via `@tanstack/zod-adapter`. Use `loader` for data fetching, `beforeLoad` for guards/redirects, and `createRootRouteWithContext` for dependency injection. Version: v1.x (stable).

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `createFileRoute` for all file-based routes - NEVER define routes manually when using the router plugin)**

**(You MUST validate search params with `validateSearch` - NEVER read raw `window.location.search`)**

**(You MUST use `beforeLoad` for auth guards and redirects - NEVER check auth inside component render)**

**(You MUST pass services via router context - NEVER import them directly in loaders (breaks testability))**

**(You MUST use `<Outlet />` in layout routes to render child content - forgetting it renders nothing)**

</critical_requirements>

---

**Auto-detection:** TanStack Router, createFileRoute, createRootRoute, createRootRouteWithContext, createRouter, RouterProvider, Outlet, useNavigate, useSearch, useParams, useLoaderData, useRouteContext, routeTree.gen, tanstack/react-router, tanstack/router-plugin, validateSearch, zodValidator, beforeLoad, loader, notFound, redirect

**When to use:**

• Building React SPAs with type-safe client-side routing
• File-based routing with automatic route tree generation
• Validated and type-safe URL search parameters
• Route-level data loading with caching
• Nested layouts with shared UI across child routes
• Authentication guards and route protection
• Code splitting routes for performance

**Key patterns covered:**

• File-based routing setup with Vite plugin
• Route definitions (`createFileRoute`, `createRootRoute`)
• Type-safe navigation (`Link`, `useNavigate`, `redirect`)
• Search params validation with Zod
• Route loaders and `beforeLoad` middleware
• Nested layouts and pathless layout routes
• Route context and dependency injection
• Authentication guards and protected routes
• Code splitting with `autoCodeSplitting`
• Error, pending, and not-found handling
• External data fetching library integration in loaders
• Devtools setup

**When NOT to use:**

• Server-rendered apps with SSR needs (use an SSR framework instead)
• Simple apps with 1-2 pages (a lightweight router or no router)
• Static sites without client-side navigation

---

Examples

• [Core Setup & Configuration](examples/core.md) -- Vite plugin, root route, entry point, devtools
• [Routes & Layouts](examples/routes.md) -- file-based routing conventions, nested layouts, pathless routes, catch-all
• [Navigation](examples/navigation.md) -- Link component, useNavigate, redirect, active states
• [Data Loading](examples/data-loading.md) -- loaders, beforeLoad, external data fetching integration, SWR caching
• [Search Params](examples/search-params.md) -- Zod validation, updating params, search middleware
• [Auth & Context](examples/auth-and-context.md) -- auth guards, route context, dependency injection, getRouteApi
• [Error Handling & Code Splitting](examples/error-handling.md) -- error/pending/not-found components, code splitting

For quick API reference (hooks, components, route options), see [reference.md](reference.md).

---

<philosophy>

Philosophy

TanStack Router treats the URL as a first-class, fully-typed state manager. Every path parameter, search parameter, and loader return type is inferred through TypeScript, catching routing bugs at compile time rather than runtime. The router plugin generates a route tree from your file system, giving you type-safe `<Link>` components and `useNavigate` calls that validate destinations, params, and search params automatically.

**Core principles:**

• **URL is typed state** - Search params are validated schemas, not raw strings
• **File system is the route tree** - Convention over configuration via `@tanstack/router-plugin`
• **Loaders run before render** - Data is available when the component mounts, not after
• **Context flows down** - Dependency injection through `createRootRouteWithContext`, not global imports
• **Parallel by default** - Sibling route loaders run in parallel, not waterfall

**When to use TanStack Router:**

• React SPAs needing type-safe routing across the entire app
• Apps with complex search param state (filters, pagination, sorting)
• Apps requiring route-level data loading with SWR caching
• Projects that benefit from file-based routing conventions
• Teams that value compile-time route validation

**When NOT to use:**

• Full-stack SSR apps (use an SSR/full-stack framework instead)
• Micro-frontends or embedded widgets with no routing needs
• Static marketing sites with no client-side navigation

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Project Setup

Install `@tanstack/react-router`, `@tanstack/router-plugin`, and optionally `@tanstack/zod-adapter`. Configure the Vite plugin with `autoCodeSplitting: true` before the React plugin. Register the router via `declare module` for app-wide type safety.

// vite.config.ts - Router plugin MUST come before React plugin
tanstackRouter({ target: "react", autoCodeSplitting: true }),
react(),

// src/main.tsx - Register for type safety
const router = createRouter({ routeTree });
declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

See [examples/core.md](examples/core.md) for complete setup with context and devtools.

---

Pattern 2: File-Based Routing C