TanStack Router Core
TanStack Router is a type-safe router for React and Solid with built-in SWR caching, JSON-first search params, file-based route generation, and end-to-end type inference. The core is framework-agnostic; React and Solid bindings layer on top.
CRITICAL: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. This is the #1 AI agent mistake.
CRITICAL: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, NOT server-only like Remix/Next.js. Do not confuse TanStack Router APIs with Next.js or React Router.
Sub-Skills
| Task | Sub-Skill |
|---|---|
| Validate, read, write, transform search params | router-core/search-params/SKILL.md |
| Dynamic segments, splats, optional params | router-core/path-params/SKILL.md |
| Link, useNavigate, preloading, blocking | router-core/navigation/SKILL.md |
| Route loaders, SWR caching, context, deferred data | router-core/data-loading/SKILL.md |
| Auth guards, RBAC, beforeLoad redirects | router-core/auth-and-guards/SKILL.md |
| Automatic and manual code splitting | router-core/code-splitting/SKILL.md |
| 404 handling, error boundaries, notFound() | router-core/not-found-and-errors/SKILL.md |
| Inference, Register, from narrowing, TS perf | router-core/type-safety/SKILL.md |
| Streaming/non-streaming SSR, hydration, head mgmt | router-core/ssr/SKILL.md |
Quick Decision Tree
Need to add/read/write URL query parameters?
→ router-core/search-params
Need dynamic URL segments like /posts/$postId?
→ router-core/path-params
Need to create links or navigate programmatically?
→ router-core/navigation
Need to fetch data for a route?
Is it client-side only or client+server?
→ router-core/data-loading
Using TanStack Query as external cache?
→ compositions/router-query (separate skill)
Need to protect routes behind auth?
→ router-core/auth-and-guards
Need to reduce bundle size per route?
→ router-core/code-splitting
Need custom 404 or error handling?
→ router-core/not-found-and-errors
Having TypeScript issues or performance problems?
→ router-core/type-safety
Need server-side rendering?
→ router-core/ssrMinimal Working Example
// src/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'
export const Route = createRootRoute({
component: () => <Outlet />,
})// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/')({
component: () => <h1>Home</h1>,
})// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
const router = createRouter({ routeTree })
// REQUIRED for type safety — without this, Link/useNavigate have no autocomplete
declare module '@tanstack/react-router' {
interface Register {
router: typeof router
}
}
export default router// src/main.tsx
import { RouterProvider } from '@tanstack/react-router'
import router from './router'
function App() {
return <RouterProvider router={router} />
}Common Mistakes
HIGH: createFileRoute path string must match the file path
The Vite plugin manages the path string in createFileRoute. Do not change it manually — it must match the file's location under src/routes/:
// File: src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
// ✅ matches file path
component: PostPage,
})
export const Route = createFileRoute('/post/$postId')({
// ❌ silent mismatch
component: PostPage,
})The plugin auto-generates this string. If you rename a route file, the plugin updates it. Never edit the path string by hand.
Version Note
This skill targets @tanstack/router-core v1.166.2 and @tanstack/react-router v1.166.2. APIs are stable. Splat routes use $ (not *); the * compat alias will be removed in v2.