/tanstack-router

name: tanstack-router
description: 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.
license: MIT
allowed-tools: [Bash, Read, Write, Edit]
metadata:
  version: 1.0.0
  author: Claude Skills Maintainers
  last-verified: 2026-08-03
  production-tested: true
  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

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

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

**Latest version:** v1.170.18 (verified 2026-08-03)

Vite Configuration

// 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

// 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

// 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)

// 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

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:**

bun add @tanstack/router-devtools

Error 2: Vite Plugin Order

**Problem:** Routes not auto-generated.

**Solution:** TanStackRouterVite MUST come before react():

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

Error 3: Type Registration Missing

**Problem:** `Link to` not typed.

**Solution:**

// 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`:

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

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

// 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 `