router-core

1---2name: router-core3description: >-4  Framework-agnostic core concepts for TanStack Router: route trees,5  createRouter, createRoute, createRootRoute, createRootRouteWithContext,6  addChildren, Register type declaration, route matching, route sorting,7  file naming conventions. Entry point for all router skills.8metadata:9  type: core10  library: tanstack-router11  library_version: '1.171.15'12---13 14# TanStack Router Core15 16TanStack 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.17 18> **CRITICAL**: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. This is the #1 AI agent mistake.19 20> **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.21 22Use this entry skill to choose one primary sub-skill. Do not load the full catalog. Load a second sub-skill only when the task crosses a real boundary, such as an authenticated loader that needs both `auth-and-guards` and `data-loading`.23 24## Sub-Skills25 26| Task                                               | Sub-Skill                                                                    |27| -------------------------------------------------- | ---------------------------------------------------------------------------- |28| Validate, read, write, transform search params     | [router-core/search-params/SKILL.md](./search-params/SKILL.md)               |29| Dynamic segments, splats, optional params          | [router-core/path-params/SKILL.md](./path-params/SKILL.md)                   |30| Link, useNavigate, preloading, blocking            | [router-core/navigation/SKILL.md](./navigation/SKILL.md)                     |31| Route loaders, SWR caching, context, deferred data | [router-core/data-loading/SKILL.md](./data-loading/SKILL.md)                 |32| Auth guards, RBAC, beforeLoad redirects            | [router-core/auth-and-guards/SKILL.md](./auth-and-guards/SKILL.md)           |33| Automatic and manual code splitting                | [router-core/code-splitting/SKILL.md](./code-splitting/SKILL.md)             |34| 404 handling, error boundaries, notFound()         | [router-core/not-found-and-errors/SKILL.md](./not-found-and-errors/SKILL.md) |35| Inference, Register, from narrowing, TS perf       | [router-core/type-safety/SKILL.md](./type-safety/SKILL.md)                   |36| Streaming/non-streaming SSR, hydration, head mgmt  | [router-core/ssr/SKILL.md](./ssr/SKILL.md)                                   |37 38## Quick Decision Tree39 40```41Need to add/read/write URL query parameters?42  → router-core/search-params43 44Need dynamic URL segments like /posts/$postId?45  → router-core/path-params46 47Need to create links or navigate programmatically?48  → router-core/navigation49 50Need to fetch data for a route?51  Is it client-side only or client+server?52    → router-core/data-loading53  Using TanStack Query as external cache?54    → compositions/router-query (separate skill)55 56Need to protect routes behind auth?57  → router-core/auth-and-guards58 59Need to reduce bundle size per route?60  → router-core/code-splitting61 62Need custom 404 or error handling?63  → router-core/not-found-and-errors64 65Having TypeScript issues or performance problems?66  → router-core/type-safety67 68Need server-side rendering?69  → router-core/ssr70```71 72## Cross-Cutting Completion Checks73 74For route refactors:75 761. Rename or move the route file; do not hand-edit the generated `createFileRoute` path.772. Regenerate `routeTree.gen.ts` with the configured Router plugin or CLI.783. Update links, redirects, `from` narrowing, params, and tests that reference the old route.794. Run type tests and a production build. A typecheck alone does not prove route generation or bundling works.80 81For response schema changes:82 831. Update the source model and shared validation schema.842. Update the server function or API serializer so the field exists at runtime.853. Update loader and component consumers without casts.864. Assert the actual response payload in a unit or integration test. Typechecking cannot catch a serializer that omits the new field.87 88## Minimal Working Example89 90```tsx91// src/routes/__root.tsx92import { createRootRoute, Outlet } from '@tanstack/react-router'93 94export const Route = createRootRoute({95  component: () => <Outlet />,96})97```98 99```tsx100// src/routes/index.tsx101import { createFileRoute } from '@tanstack/react-router'102 103export const Route = createFileRoute('/')({104  component: () => <h1>Home</h1>,105})106```107 108```tsx109// src/router.tsx110import { createRouter } from '@tanstack/react-router'111import { routeTree } from './routeTree.gen'112 113const router = createRouter({ routeTree })114 115// REQUIRED for type safety — without this, Link/useNavigate have no autocomplete116declare module '@tanstack/react-router' {117  interface Register {118    router: typeof router119  }120}121 122export default router123```124 125```tsx126// src/main.tsx127import { RouterProvider } from '@tanstack/react-router'128import router from './router'129 130function App() {131  return <RouterProvider router={router} />132}133```134 135## Common Mistakes136 137### HIGH: createFileRoute path string must match the file path138 139The Vite plugin manages the path string in `createFileRoute`. Do not change it manually — it must match the file's location under `src/routes/`:140 141```tsx142// File: src/routes/posts/$postId.tsx143export const Route = createFileRoute('/posts/$postId')({144  // ✅ matches file path145  component: PostPage,146})147 148export const Route = createFileRoute('/post/$postId')({149  // ❌ silent mismatch150  component: PostPage,151})152```153 154The plugin auto-generates this string. If you rename a route file, the plugin updates it. Never edit the path string by hand.155 156## Version Note157 158This skill targets `@tanstack/router-core` v1.171.15. Splat routes use `$` (not `*`); the `*` compat alias will be removed in v2.159