router-core

TanStack Router Core

TanStack Router 是适用于 React 和 Solid 的类型安全路由器，内置 SWR 缓存、JSON 优先的搜索参数、基于文件的路由生成以及端到端类型推断。其核心与框架无关；React 和 Solid 绑定构建于其上。

CRITICAL：TanStack Router 类型完全通过推断得出。绝不要进行类型断言，也不要为推断出的值添加类型注解。这是 AI Agent 最常犯的错误。

CRITICAL：TanStack Router 以客户端为先。加载器默认在客户端运行，并非像 Remix/Next.js 那样仅在服务器运行。不要将 TanStack Router API 与 Next.js 或 React Router 混淆。

使用此入口技能选择一个主要子技能。不要加载完整目录。仅当任务涉及实际边界时，才加载第二个子技能，例如需要同时使用 auth-and-guards 和 data-loading 的身份验证加载器。

子技能

任务	子技能
验证、读取、写入、转换搜索参数	router-core/search-params/SKILL.md
动态片段、通配片段、可选参数	router-core/path-params/SKILL.md
链接、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、from 窄化、TS 性能	router-core/type-safety/SKILL.md
流式/非流式 SSR、水合、head 管理	router-core/ssr/SKILL.md

快速决策树

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

跨领域完成检查

对于路由重构：

1. 重命名或移动路由文件；不要手动编辑生成的 createFileRoute 路径。
2. 使用已配置的 Router 插件或 CLI 重新生成 routeTree.gen.ts。
3. 更新引用旧路由的链接、重定向、from 窄化、参数和测试。
4. 运行类型测试和生产构建。仅进行类型检查无法证明路由生成或打包正常。

对于响应架构变更：

1. 更新源模型和共享验证架构。
2. 更新服务器函数或 API 序列化器，确保该字段在运行时存在。
3. 更新加载器和组件使用方，不要使用类型断言。
4. 在单元测试或集成测试中断言实际响应负载。类型检查无法发现序列化器遗漏新字段的问题。

最小可运行示例

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

常见错误

HIGH：createFileRoute 路径字符串必须与文件路径一致

Vite 插件会管理 createFileRoute 中的路径字符串。不要手动更改——它必须与文件在 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,
})

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

版本说明

此技能针对 @tanstack/router-core v1.171.15。通配路由使用 $（而非 *）；* 兼容别名将在 v2 中移除。