router-core

name	router-core
description	Framework-agnostic core concepts for TanStack Router: route trees, createRouter, createRoute, createRootRoute, createRootRouteWithContext, addChildren, Register type declaration, route matching, route sorting, file naming conventions. Entry point for all router skills.
type	core
library	tanstack-router
library_version	1.166.2

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

Minimal 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.