Agent skill

tanstack-router

TanStack Router type-safe file-based routing for React. Use for SPAs, TanStack Query integration, Cloudflare Workers, or encountering devtools, type safety, loader, Vite bundling errors.

View SKILL.md on GitHub Repository
Stars 109
Forks 14

Install this agent skill to your Project

npx add-skill https://github.com/secondsky/claude-skills/tree/main/plugins/tanstack-router/skills/tanstack-router

Metadata

Additional technical details for this skill

author
Claude Skills Maintainers
version
1.0.0
keywords
tanstack router react router type-safe routing file-based routing client-side routing spa routing route loaders data loading navigation vite plugin cloudflare workers tanstack query integration typescript routing route params nested routes code splitting
last verified
1762473600
production tested
YES

SKILL.md

TanStack Router Skill

Build type-safe, file-based routing for React SPAs with TanStack Router, optimized for Cloudflare Workers deployment.

When to Use This Skill

Auto-triggers when you mention:

  • "TanStack Router" or "type-safe routing"
  • "file-based routing" or "route configuration"
  • "React routing" with TypeScript emphasis
  • "route loaders" or "data loading in routes"
  • "Cloudflare Workers routing"

Use this skill when:

  • Building SPAs with type-safe navigation
  • Implementing file-based routing (like Next.js)
  • Need route-level data loading
  • Integrating routing with TanStack Query
  • Deploying to Cloudflare Workers
  • Want better TypeScript support than React Router

Quick Start

Installation

bash
bun add @tanstack/react-router @tanstack/router-devtools
bun add -d @tanstack/router-plugin

Latest version: v1.134.13 (verified 2025-11-07)

Vite Configuration

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

export default defineConfig({
  plugins: [
    TanStackRouterVite(), // MUST come before react()
    react(),
  ],
})

Basic Setup

typescript
// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'

export const Route = createRootRoute({
  component: () => (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <hr />
      <Outlet />
    </div>
  ),
})

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: () => <h1>Home Page</h1>,
})

// src/routes/about.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({
  component: () => <h1>About Page</h1>,
})

// src/main.tsx
import { createRouter, RouterProvider } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen' // Auto-generated

const router = createRouter({ routeTree })

function App() {
  return <RouterProvider router={router} />
}

Key Features

1. Type-Safe Navigation

typescript
// Fully typed!
<Link to="/posts/$postId" params={{ postId: '123' }} />

// TypeScript error if route doesn't exist
<Link to="/invalid-route" /> // ❌ Error!

2. Route Loaders (Data Fetching)

typescript
// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId) // Fully typed!
    return { post }
  },
  component: ({ useLoaderData }) => {
    const { post } = useLoaderData()
    return <h1>{post.title}</h1>
  },
})

3. TanStack Query Integration

typescript
import { queryOptions } from '@tanstack/react-query'

const postQueryOptions = (postId: string) =>
  queryOptions({
    queryKey: ['posts', postId],
    queryFn: () => fetchPost(postId),
  })

export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postQueryOptions(params.postId)),
  component: () => {
    const { postId } = Route.useParams()
    const { data: post } = useQuery(postQueryOptions(postId))
    return <h1>{post.title}</h1>
  },
})

Common Errors & Solutions

Error 1: Devtools Dependency Resolution

Problem: Build fails with @tanstack/router-devtools-core not found.

Solution:

bash
bun add @tanstack/router-devtools

Error 2: Vite Plugin Order

Problem: Routes not auto-generated.

Solution: TanStackRouterVite MUST come before react():

typescript
plugins: [
  TanStackRouterVite(), // First!
  react(),
]

Error 3: Type Registration Missing

Problem: Link to not typed.

Solution:

typescript
// src/routeTree.gen.ts is auto-generated
// Import it in main.tsx to register types
import { routeTree } from './routeTree.gen'

Error 4: Loader Not Running

Problem: Loader function not called on navigation.

Solution: Ensure route exports Route:

typescript
export const Route = createFileRoute('/path')({ loader: ... })

Error 5: Memory Leak with Forms

Problem: Production crashes when using TanStack Form + Router.

Solution: This is a known issue (#5734). Workaround: Use React Hook Form instead, or wait for fix.

Cloudflare Workers Deployment

Vite Config

typescript
import { defineConfig } from 'vite'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
    react(),
    cloudflare(),
  ],
})

API Backend Pattern

typescript
// functions/api/posts.ts
export async function onRequestGet({ env }) {
  const { results } = await env.DB.prepare('SELECT * FROM posts').all()
  return Response.json(results)
}

// Client-side route
export const Route = createFileRoute('/posts')({
  loader: async () => {
    const posts = await fetch('/api/posts').then(r => r.json())
    return { posts }
  },
})

Templates

All templates in ~/.claude/skills/tanstack-router/templates/:

  1. package.json - Dependencies and versions
  2. vite.config.ts - Vite plugin setup
  3. basic-routes/ - File-based routing structure
  4. route-with-loader.tsx - Data loading example
  5. query-integration.tsx - TanStack Query pattern
  6. nested-routes/ - Layout pattern
  7. cloudflare-deployment.md - Workers setup guide

Reference Docs

Deep-dive guides in ~/.claude/skills/tanstack-router/references/:

  1. file-based-routing.md - Route structure conventions
  2. type-safety.md - TypeScript patterns
  3. data-loading.md - Loaders and TanStack Query
  4. cloudflare-workers.md - Deployment guide
  5. common-errors.md - All 7+ errors with solutions
  6. migration-guide.md - From React Router

Integration with Existing Skills

Works with:

  • tanstack-query - Recommended for data fetching
  • tanstack-table - Display data from routes
  • cloudflare-worker-base - API backend
  • tailwind-v4-shadcn - UI styling

Token Efficiency

Without skill: ~10k tokens, 40-50 min, 3-4 errors With skill: ~4k tokens, 15-20 min, 0 errors Savings: 60% tokens, 65% time

Production Validation

Tested with:

  • React 19.2, Vite 6.0, TypeScript 5.8
  • Cloudflare Workers (Wrangler 4.0)
  • TanStack Query v5.90.7

Stack compatibility:

  • ✅ Cloudflare Workers + Static Assets
  • ✅ TanStack Query integration
  • ✅ TypeScript strict mode

Last Updated: 2025-11-07 Library Version: @tanstack/react-router v1.134.13

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

secondsky/claude-skills

skill-name

[TODO: Write comprehensive description in third-person. Start with "This skill provides..." or "This skill should be used when..."] [TODO: Add "Use when" scenarios - specific situations where Claude should use this skill] [TODO: Add keywords - technologies, use cases, error messages that should trigger this skill]

109 14
Explore
secondsky/claude-skills

websocket-implementation

Implements real-time WebSocket communication with connection management, room-based messaging, and horizontal scaling. Use when building chat systems, live notifications, collaborative tools, or real-time dashboards.

109 14
Explore
secondsky/claude-skills

ai-sdk-ui

109 14
Explore
secondsky/claude-skills

bun-nextjs

This skill should be used when the user asks about "Next.js with Bun", "Bun and Next", "running Next.js on Bun", "Next.js development with Bun", "create-next-app with Bun", or building Next.js applications using Bun as the runtime.

109 14
Explore
secondsky/claude-skills

bun-sqlite

Use for bun:sqlite, SQLite operations, prepared statements, transactions, and queries.

109 14
Explore
secondsky/claude-skills

bun-sveltekit

Use when building or running SvelteKit apps on Bun, including SSR, adapters, and Bun-specific APIs

109 14
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results