Skip to main content
skill CX Codex

tanstack-router · oakoss — Claude Code skill: what it does, how to install

tanstack-router adds guidance for type-safe file-based React routing with @tanstack/react-router. Useful for loaders, search param validation, and code splitting.

MIT 150 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code
Open on GitHub

What tanstack-router does

This skill guides coding agents through @tanstack/react-router version 1.3 conventions and @tanstack/router-plugin setup. It covers route declarations with createFileRoute, lazy loading with createLazyFileRoute, search parameter parsing with zodValidator, and navigation blockers.

Plugin order matters. In your Vite configuration, TanStackRouterVite must run before react(), or route generation fails. The skill also enforces safe data patterns, prioritizing ensureQueryData over prefetchQuery inside loaders and replacing useEffect waterfalls with parallel fetching via Promise.all.

What it helps with

  • Set up file-based routes with @tanstack/router-plugin in Vite
  • Validate search parameters using zodValidator
  • Integrate TanStack Query loaders using ensureQueryData
  • Implement pathless authentication layouts using _authenticated.tsx

Example prompts for the agent

  • Set up a dynamic route posts.$postId.tsx with a typed loader and search param schema
  • Add a navigation blocker with useBlocker to prevent losing unsaved form changes
  • Split the dashboard bundle using dashboard.lazy.tsx and createLazyFileRoute

How to install tanstack-router

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-router/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-router/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-router

How to install tanstack-router in Claude Code?

Run npx skills add oakoss/agent-skills --skill tanstack-router -a claude-code in your terminal. The configuration is placed at ~/.claude/skills/tanstack-router/SKILL.md.

What does the tanstack-router skill do?

It provides rules and patterns for file-based routing, search parameter handling, and data loading in React. It stops agents from putting route data fetches inside useEffect.

Why does the skill recommend ensureQueryData over prefetchQuery in loaders?

prefetchQuery returns void and swallows errors. Route loaders require ensureQueryData because it resolves actual data and throws when requests fail.

Source text

SKILL.md · MIT
---
name: tanstack-router
description: 'Type-safe, file-based React routing with route loaders, search params validation, code splitting, preloading, navigation, route context, and TanStack Query integration. Use when setting up file-based routing, adding search params validation, implementing route loaders, code splitting routes, configuring virtual file routes, protecting routes with auth guards, or fixing type registration errors. Use for router setup, navigation patterns, URL state management, data loading.'
license: MIT
metadata:
  author: oakoss
  version: '1.3'
  source: 'https://tanstack.com/router/latest/docs'
user-invocable: false
---

# TanStack Router

Type-safe, file-based routing for React with route-level data loading, search params validation, code splitting, and TanStack Query integration.

**Package:** `@tanstack/react-router` | **Plugin:** `@tanstack/router-plugin`

## Quick Reference

| Pattern                           | Usage                                   |
| --------------------------------- | --------------------------------------- |
| `createFileRoute('/path')`        | Define file-based route                 |
| `createRootRouteWithContext<T>()` | Root route with typed context           |
| `createLazyFileRoute('/path')`    | Code-split route component              |
| `zodValidator(schema)`            | Search params validation                |
| `Route.useLoaderData()`           | Access loader data in component         |
| `Route.useParams()`               | Type-safe route params                  |
| `Route.useSearch()`               | Type-safe search params                 |
| `useNavigate()`                   | Programmatic navigation                 |
| `useBlocker()`                    | Block navigation (dirty forms)          |
| `notFound()`                      | Throw 404 from loader                   |
| `getRouteApi('/path')`            | Type-safe hooks in split files          |
| `stripSearchParams(defaults)`     | Clean default values from URLs          |
| `retainSearchParams(['key'])`     | Preserve params across navs             |
| `useAwaited({ promise })`         | Suspend until deferred promise resolves |
| `useCanGoBack()`                  | Check if router can go back safely      |

## Data Loading

| Method               | Returns | Throws | Use Case                                         |
| -------------------- | ------- | ------ | ------------------------------------------------ |
| `ensureQueryData`    | Data    | Yes    | Route loaders (recommended)                      |
| `prefetchQuery`      | void    | No     | Background prefetching                           |
| `fetchQuery`         | Data    | Yes    | Immediate data need                              |
| `defer()` (optional) | Promise | No     | Stream non-critical data (promises auto-handled) |

## Preloading

| Strategy     | Behavior                  | Use Case                    |
| ------------ | ------------------------- | --------------------------- |
| `'intent'`   | Preload on hover/focus    | Default for most links      |
| `'render'`   | Preload when Link mounts  | Critical next pages         |
| `'viewport'` | Preload when Link in view | Below-fold content          |
| `false`      | No preloading             | Heavy, rarely-visited pages |

## File Organization

| File                 | Purpose                      |
| -------------------- | ---------------------------- |
| `__root.tsx`         | Root route with `<Outlet />` |
| `index.tsx`          | Index route for `/`          |
| `posts.$postId.tsx`  | Dynamic param route          |
| `_authenticated.tsx` | Pathless layout (auth guard) |
| `dashboard.lazy.tsx` | Code-split component         |

## Common Mistakes

| Mistake                           | Fix                                                   |
| --------------------------------- | ----------------------------------------------------- |
| Missing router type registration  | Add `declare module` with `Register` interface        |
| `useParams()` without `from`      | Always pass `from: '/route/path'` for exact types     |
| `useNavigate()` for regular links | Use `<Link>` for `<a>` tags, a11y, preloading         |
| `prefetchQuery` in loaders        | Use `ensureQueryData` (returns data, throws errors)   |
| Fetching in `useEffect`           | Use route loaders (prevents waterfalls)               |
| Sequential fetches in loader      | Use `Promise.all` for parallel requests               |
| Missing leading slash             | Always `'/about'` not `'about'`                       |
| TanStackRouterVite after react()  | Plugin MUST come before `react()` in Vite config      |
| `strict: false` params unparsed   | Use strict mode or manually parse after navigation    |
| Pathless route notFoundComponent  | Define `notFoundComponent` on child routes instead    |
| Aborted loader undefined error    | Guard `errorComponent` with `if (!error) return null` |
| No `loaderDeps` declared          | Declare deps so loader only re-runs when they change  |

## Delegation

- **TanStack Query patterns** — data fetching, caching, mutations: use `tanstack-query` skill
- **TanStack Start** — server functions, SSR, server-side auth: use `tanstack-start` skill
- **TanStack Table** — table rendering with router search params: use `tanstack-table` skill
- **Router + Query integration** — loader data flow, preloading: see [Loader Data Flow Patterns](references/loader-query-patterns.md)

> If the `tanstack-devtools` skill is available, delegate router state debugging and route tree inspection to it.

## References

- [Setup](references/setup.md) — installation, Vite config, file structure, app setup, router default options
- [Type Safety](references/type-safety.md) — register router, `from` param, `strict: false`, type utilities, getRouteApi
- [Data Loading](references/data-loading.md) — route loaders, Query integration, parallel loading, streaming, deferred data, abort signal, loaderDeps
- [Search Params](references/search-params.md) — validation, strip/retain middleware, fine-grained subscriptions, debounce, custom serializers
- [Navigation](references/navigation.md) — Link, active styling, relative navigation, hash, route masks, blocker, scroll restoration
- [Auth and Context](references/auth-and-context.md) — beforeLoad, context inheritance, pathless layouts, dependency injection, error handling
- [Code Splitting](references/code-splitting.md) — lazy routes, auto splitting, preloading strategies, programmatic preloading
- [Virtual File Routes](references/virtual-routes.md) — rootRoute, route, index, layout, physical builders, mixing file-based and code-based routing
- [Known Issues](references/known-issues.md) — 20 documented issues with fixes, anti-patterns
- [Loader+Query Patterns](references/loader-query-patterns.md) — ensureQueryData in loaders, parallel loading, critical vs non-critical data, search-param-dependent loaders

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

tanstack-router by other authors comes first.

tanstack-router tanstack-skills A TanStack Router skill for React and Solid: file-based routing, search params and data loading with full type checking. CX Codex +1 5,200installs tanstack-router Claude Skills Maintainers tanstack-router configures type-safe file-based routing in React SPAs and resolves integration issues with TanStack Query or Cloudflare Workers. CX Codex +1 468installs tanstack-router-best-practices DeckardGer tanstack-router-best-practices — a rule set for TanStack Router in React: type safety, data loading, search params, navigation. Useful once routing in a project grows past a few pages. CX Codex +1 7,200installs react-router TanStack react-router — a skill that teaches your coding agent the React bindings for TanStack Router: hook reference, components, and a file-based routing setup on Vite. CX Codex +1 657installs tanstack-router-react-cursorrules-prompt-file PatrickJS tanstack-router-react-cursorrules-prompt-file enforces TanStack Router v1 patterns in React: file-based routing, Zod search param validation, loaders, and auth guards via beforeLoad. CX Codex +1 ★ 41,178repo stars router-core TanStack router-core is a TanStack Router skill that routes tasks to the right sub-skill and reinforces type inference and client-first loader rules. CX Codex +1 711installs react-tanstack-router-query PatrickJS react-tanstack-router-query guides AI assistants on structuring React SPAs with TanStack Router v1 and TanStack Query v5 to fetch data in loaders before rendering. CX Codex +1 ★ 41,178repo stars tanstack-vue-router-skilld skilld-dev tanstack-vue-router-skilld — a skill for working with @tanstack/vue-router, the type-safe Vue router. Teaches the agent setup rules, file-based routes, composables returning Ref, links and loaders. CX Codex +1 101installs

From the same set106

The whole set →
tanstack-table Guides React headless table architecture with TanStack Table v8, covering server pagination, filtering, and render bug prevention. CX Codex +1 155installs changesets The changesets skill manages package versions and changelogs in a monorepo. Use it to coordinate releases and publish packages to npm. CX Codex +1 154installs opentofu Get help writing and reviewing OpenTofu configurations and Pulumi programs. Use the skill to manage infrastructure code, state, and environment setups. CX Codex +1 153installs arktype-validation arktype-validation — a skill for ArkType, where schemas are TypeScript-shaped strings. Covers morphs, scopes and ArkEnv checks for environment variables. Handy for runtime validation that stays close to the type syntax. CX Codex +1 153installs api-testing api-testing is a Claude Code skill for writing REST API integration tests and checking endpoint responses. It activates for HTTP mocking, response validation, and API error tests. CX Codex +1 149installs github-actions Create and configure GitHub Actions workflows, from event triggers and build matrices to caching and authentication. Useful for automating tests, releases, and deployments. CX Codex +1 149installs git-workflow git-workflow guides AI coding agents through trunk-based development, conventional commits, reusable GitHub Actions workflows, and Git history repair. CX Codex +1 149installs ux-designer ux-designer is a Claude Code skill that guides AI agents from information architecture to developer handoff, with usability and accessibility checks. CX Codex +1 148installs

Project sponsors

Companies that keep this analytics open