web-routing-tanstack-router

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 Conventions

The router plugin generates a typed route tree from your file structure. Key conventions:

| Convention | Example | Purpose | | ------------ | -------------------- | ---------------------------------------- | | __root.tsx | __root.tsx | Root layout, wraps entire app | | index.tsx | posts/index.tsx | Index route for directory (/posts) | | $param | $postId/index.tsx | Dynamic path parameter | | _prefix | _authenticated.tsx | Pathless layout (no URL segment) | | route.tsx | posts/route.tsx | Layout for directory children | | suffix_ | posts_.detail.tsx | Non-nested route (escapes parent layout) | | $ | $.tsx | Splat/catch-all route | | -prefix | -components.tsx | Ignored by router (not a route) | | (group) | (admin)/ | Organizational grouping (no URL effect) |

// src/routes/posts/index.tsx
export const Route = createFileRoute("/posts/")({
  component: PostsIndex,
});

See [examples/routes.md](examples/routes.md) for nested layouts, pathless routes, non-nested routes, and catch-all routes.

Pattern 3: Type-Safe Navigation

TanStack Router validates all navigation destinations, params, and search params at compile time.

// Declarative - Link component
<Link to="/posts/$postId" params={{ postId: post.id }} preload="intent">
  {post.title}
</Link>

// Imperative - after side effects
const navigate = useNavigate();
await navigate({ to: "/posts/$postId", params: { postId: post.id }, replace: true });

// In loaders/beforeLoad - redirect
throw redirect({ to: "/login", search: { redirect: location.href } });

See [examples/navigation.md](examples/navigation.md) for active states, search param updaters, and navigation decision tree.

Pattern 4: Search Params Validation

Validate and type search params with validateSearch. Use Zod adapter for schema-based validation with fallback() for safe defaults.

import { zodValidator, fallback