router-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Router Core

TanStack Router 核心

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.

TanStack Router 是一款适用于 React 和 Solid 的类型安全路由库，内置 SWR 缓存、JSON 优先的搜索参数、基于文件的路由生成能力以及端到端类型推断。其核心是框架无关的，React 和 Solid 的绑定在核心之上实现。

重要提示：TanStack Router 的类型是完全自动推断的。永远不要对推断出的值进行类型断言，也不要手动添加类型注解。这是AI Agent最常犯的错误。

重要提示：TanStack Router 是客户端优先的。加载器默认在客户端运行，不像 Remix/Next.js 那样仅在服务端运行。不要将 TanStack Router 的API和 Next.js 或 React Router 的API混淆。

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

任务	子技能
验证、读取、写入、转换搜索参数	router-core/search-params/SKILL.md
动态路由段、通配符、可选参数	router-core/path-params/SKILL.md
Link、useNavigate、预加载、路由阻断	router-core/navigation/SKILL.md
路由加载器、SWR 缓存、上下文、延迟数据	router-core/data-loading/SKILL.md
鉴权守卫、RBAC、beforeLoad 重定向	router-core/auth-and-guards/SKILL.md
自动与手动代码分割	router-core/code-splitting/SKILL.md
404 处理、错误边界、notFound()	router-core/not-found-and-errors/SKILL.md
类型推断、Register、类型收窄、TS 性能优化	router-core/type-safety/SKILL.md
流式/非流式 SSR、 hydration、head 管理	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

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

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>首页</h1>,
})

tsx

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// 类型安全必须配置 — 缺少该配置的话，Link/useNavigate 不会有自动补全
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

高优先级错误：createFileRoute 路径字符串必须和文件路径匹配

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.

Vite 插件会管理

createFileRoute

中的路径字符串。不要手动修改它 — 它必须和文件在

src/routes/

下的存放路径完全匹配：

tsx

// 文件路径: src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  // ✅ 和文件路径匹配
  component: PostPage,
})

export const Route = createFileRoute('/post/$postId')({
  // ❌ 无提示的路径不匹配错误
  component: PostPage,
})

该字符串由插件自动生成。如果你重命名路由文件，插件会自动更新它。永远不要手动编辑路径字符串。

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.

本技能适配

@tanstack/router-core

v1.166.2 和

@tanstack/react-router

v1.166.2 版本。API 稳定。通配符路由使用

（而非

）；

兼容别名将在 v2 版本中移除。