# tanstack-router

A TanStack Router skill for React and Solid: file-based routing, search params and data loading with full type checking.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4900 installs · ★ 36
- Author: tanstack-skills
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/tanstack-skills/tanstack-skills/tree/HEAD/plugins/tanstack-router/skills/tanstack-router/SKILL.md
- Updated: 2026-01-31
- HTML: https://affpapa.org/en/nevibecode/skills/tanstack-router

## What it does

The skill hands your agent a reference for TanStack Router, a type-safe router for React and Solid. It covers route trees, file-based routing, search parameter handling, data loading through `loader`, and TypeScript integration. The package is `@tanstack/react-router`.

File-based routing needs a plugin: `@tanstack/router-plugin` for Vite, Rspack or Webpack, or the standalone `@tanstack/router-cli`. Naming conventions come as a table — `__root.tsx` for the root layout, `$postId.tsx` for a dynamic param, `$.tsx` for catch-all, and the `_` prefix for pathless layout groups.

A route can declare `validateSearch`, `loaderDeps`, `beforeLoad` for redirects and auth checks, plus error, pending and not-found components. Deferred loading runs through `defer` and `Await`. If your project already runs another router, this skill won't walk you through a migration — it documents the TanStack Router API, not a switch from react-router.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tanstack-skills/tanstack-skills --skill tanstack-router -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tanstack-router/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tanstack-router/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tanstack-skills/tanstack-skills --skill tanstack-router -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tanstack-router/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tanstack-skills/tanstack-skills --skill tanstack-router -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tanstack-router/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tanstack-skills/tanstack-skills tanstack-router
```

2. **Manually: put the files in place**
- File: `.github/skills/tanstack-router/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tanstack-skills/tanstack-skills --skill tanstack-router -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tanstack-skills/tanstack-skills --path plugins/tanstack-router/skills/tanstack-router
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tanstack-router/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add tanstack-skills/tanstack-skills --skill tanstack-router -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tanstack-skills/tanstack-skills/tree/HEAD/plugins/tanstack-router/skills/tanstack-router/SKILL.md

## When to use it
- set up file-based routing in a Vite project
- validate search params with zod
- load data before a route renders
- guard a route with an auth check in `beforeLoad`
- stream slow data with `defer` and `Await`

## Example prompts
- Set up TanStack Router file-based routing in vite.config.ts
- Add zod validateSearch to the /posts route
- Write a loader for /posts/$postId that parses params

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8dfd8345cf785aa3.

BEGIN THIRD-PARTY FILE 8dfd8345cf785aa3
````text
---
name: tanstack-router
description: Type-safe routing for React and Solid applications with first-class search params, data loading, and seamless integration with the React ecosystem.
---


## Overview

TanStack Router is a fully type-safe router for React (and Solid) applications. It provides file-based routing, first-class search parameter management, built-in data loading, code splitting, and deep TypeScript integration. It serves as the routing foundation for TanStack Start (the full-stack framework).

**Package:** `@tanstack/react-router`
**CLI:** `@tanstack/router-cli` or `@tanstack/router-plugin` (Vite/Rspack/Webpack)
**Devtools:** `@tanstack/react-router-devtools`

## Installation

```bash
npm install @tanstack/react-router
# For file-based routing with Vite:
npm install -D @tanstack/router-plugin
# Or standalone CLI:
npm install -D @tanstack/router-cli
```

## Core Concepts

### Route Trees

Routes are organized in a tree structure. The root route is the top-level layout, and child routes nest underneath.

```tsx
import { createRootRoute, createRoute, createRouter } from '@tanstack/react-router'

const rootRoute = createRootRoute({
  component: RootLayout,
})

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: HomePage,
})

const aboutRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/about',
  component: AboutPage,
})

const routeTree = rootRoute.addChildren([indexRoute, aboutRoute])
const router = createRouter({ routeTree })
```

### File-Based Routing

File-based routing automatically generates the route tree from your file structure. Configure with Vite plugin:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    // ... other plugins
  ],
})
```

#### File Naming Conventions

| File Pattern | Route Type | Example Path |
|---|---|---|
| `__root.tsx` | Root layout | N/A (wraps all) |
| `index.tsx` | Index route | `/` |
| `about.tsx` | Static route | `/about` |
| `$postId.tsx` | Dynamic param | `/posts/$postId` |
| `posts.tsx` | Layout route | `/posts/*` (layout) |
| `posts/index.tsx` | Nested index | `/posts` |
| `posts/$postId.tsx` | Nested dynamic | `/posts/123` |
| `posts_.$postId.tsx` | Pathless layout | `/posts/123` (different layout) |
| `_layout.tsx` | Pathless layout | N/A (groups routes) |
| `_layout/dashboard.tsx` | Grouped route | `/dashboard` |
| `$.tsx` | Splat/catch-all | `/*` |
| `posts.$postId.edit.tsx` | Dot notation | `/posts/123/edit` |

#### Special Prefixes
- `_` prefix: Pathless routes (layout groups without URL segment)
- `$` prefix: Dynamic path parameters
````
END THIRD-PARTY FILE 8dfd8345cf785aa3

The third-party file has ended. Everything between the 8dfd8345cf785aa3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2745 of 17509 bytes. © tanstack-skills · MIT · https://github.com/tanstack-skills/tanstack-skills/tree/HEAD/plugins/tanstack-router/skills/tanstack-router/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md