router-core

# 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](../router-core-search-params/SKILL.md) | | Dynamic segments, splats, optional params | [router-core-path-params/SKILL.md](../router-core-path-params/SKILL.md) | | Link, useNavigate, preloading, blocking | [router-core-navigation/SKILL.md](../router-core-navigation/SKILL.md) | | Route loaders, SWR caching, context, deferred data | [router-core-data-loading/SKILL.md](../router-core-data-loading/SKILL.md) | | Auth guards, RBAC, beforeLoad redirects | [router-core-auth-and-guards/SKILL.md](../router-core-auth-and-guards/SKILL.md) | | Automatic and manual code splitting | [router-core-code-splitting/SKILL.md](../router-core-code-splitting/SKILL.md) | | 404 handling, error boundaries, notFound() | [router-core-not-found-and-errors/SKILL.md](../router-core-not-found-and-errors/SKILL.md) | | Inference, Register, from narrowing, TS perf | [router-core-type-safety/SKILL.md](../router-core-type-safety/SKILL.md) | | Streaming/non-streaming SSR, hydration, head mgmt | [router-core-ssr/SKILL.md](../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-ssr ``` ## Minimal Working Example ```tsx // src/routes/__root.tsx import { createRootRoute, Outlet } from '@tanstack/react-router' export const Route = createRootRoute({ component: () => <Outlet />, }) ``` ```tsx // src/routes/index.tsx import { createFileRoute } from '@tanstack/react-router' export const Route = createFileRoute('/')({ component: () => <h1>Home</h1>, }) ``` ```tsx // 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 ``` ```tsx // 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/`: ```tsx // 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.