tanstack-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Router

Type-safe, file-based routing for React with route-level data loading, search params validation, code splitting, and TanStack Query integration.

Package:

@tanstack/react-router

| Plugin:

@tanstack/router-plugin

这是为React打造的类型安全、基于文件的路由方案，支持路由级数据加载、搜索参数验证、代码分割以及TanStack Query集成。

包：

@tanstack/react-router

| 插件：

@tanstack/router-plugin

Quick Reference

速查参考

Pattern	Usage
`createFileRoute('/path')`	Define file-based route
`createRootRouteWithContext<T>()`	Root route with typed context
`createLazyFileRoute('/path')`	Code-split route component
`zodValidator(schema)`	Search params validation
`Route.useLoaderData()`	Access loader data in component
`Route.useParams()`	Type-safe route params
`Route.useSearch()`	Type-safe search params
`useNavigate()`	Programmatic navigation
`useBlocker()`	Block navigation (dirty forms)
`notFound()`	Throw 404 from loader
`getRouteApi('/path')`	Type-safe hooks in split files
`stripSearchParams(defaults)`	Clean default values from URLs
`retainSearchParams(['key'])`	Preserve params across navs

模式	用途
`createFileRoute('/path')`	定义基于文件的路由
`createRootRouteWithContext<T>()`	带类型化上下文的根路由
`createLazyFileRoute('/path')`	代码分割的路由组件
`zodValidator(schema)`	搜索参数验证
`Route.useLoaderData()`	在组件中访问加载器数据
`Route.useParams()`	类型安全的路由参数
`Route.useSearch()`	类型安全的搜索参数
`useNavigate()`	编程式导航
`useBlocker()`	阻止导航（针对未保存的表单）
`notFound()`	从加载器中抛出404错误
`getRouteApi('/path')`	在拆分文件中使用类型安全的钩子
`stripSearchParams(defaults)`	从URL中清除默认值
`retainSearchParams(['key'])`	在导航过程中保留指定参数

Data Loading

数据加载

Method	Returns	Throws	Use Case
`ensureQueryData`	Data	Yes	Route loaders (recommended)
`prefetchQuery`	void	No	Background prefetching
`fetchQuery`	Data	Yes	Immediate data need
`defer()`	Promise	No	Stream non-critical data

方法	返回值	是否抛出错误	使用场景
`ensureQueryData`	数据	是	路由加载器（推荐使用）
`prefetchQuery`	void	否	后台预加载
`fetchQuery`	数据	是	即时获取数据需求
`defer()`	Promise	否	流式加载非关键数据

Preloading

预加载

Strategy	Behavior	Use Case
`'intent'`	Preload on hover/focus	Default for most links
`'render'`	Preload when Link mounts	Critical next pages
`'viewport'`	Preload when Link in view	Below-fold content
`false`	No preloading	Heavy, rarely-visited pages

策略	行为	使用场景
`'intent'`	在悬停/聚焦时预加载	大多数链接的默认策略
`'render'`	当Link组件挂载时预加载	关键的下一级页面
`'viewport'`	当Link进入视口时预加载	页面下方的内容
`false`	不进行预加载	资源密集、极少访问的页面

File Organization

文件组织

File	Purpose
`__root.tsx`	Root route with `<Outlet />`
`index.tsx`	Index route for `/`
`posts.$postId.tsx`	Dynamic param route
`_authenticated.tsx`	Pathless layout (auth guard)
`dashboard.lazy.tsx`	Code-split component

文件名称	用途
`__root.tsx`	包含 `<Outlet />` 的根路由
`index.tsx`	对应 `/` 路径的索引路由
`posts.$postId.tsx`	带动态参数的路由
`_authenticated.tsx`	无路径布局（认证守卫）
`dashboard.lazy.tsx`	经过代码分割的组件

Common Mistakes

常见错误

Mistake	Fix
Missing router type registration	Add `declare module` with `Register` interface
`useParams()` without `from`	Always pass `from: '/route/path'` for exact types
`useNavigate()` for regular links	Use `<Link>` for `<a>` tags, a11y, preloading
`prefetchQuery` in loaders	Use `ensureQueryData` (returns data, throws errors)
Fetching in `useEffect`	Use route loaders (prevents waterfalls)
Sequential fetches in loader	Use `Promise.all` for parallel requests
Missing leading slash	Always `'/about'` not `'about'`
TanStackRouterVite after react()	Plugin MUST come before `react()` in Vite config
`strict: false` params unparsed	Use strict mode or manually parse after navigation
Pathless route notFoundComponent	Define `notFoundComponent` on child routes instead
Aborted loader undefined error	Guard `errorComponent` with `if (!error) return null`
No `loaderDeps` declared	Declare deps so loader only re-runs when they change

错误内容	修复方案
缺少路由类型注册	添加包含 `Register` 接口的 `declare module` 声明
使用 `useParams()` 时未传 `from` 参数	始终传入 `from: '/route/path'` 以获取精确的类型
用 `useNavigate()` 处理普通链接	对 `<a>` 标签使用 `<Link>` ，以保证可访问性和预加载功能
在加载器中使用 `prefetchQuery`	使用 `ensureQueryData` （返回数据并抛出错误）
在 `useEffect` 中进行数据请求	使用路由加载器（避免请求瀑布流）
在加载器中按顺序发起请求	使用 `Promise.all` 并行发起请求
路径缺少前导斜杠	始终使用 `'/about'` 而非 `'about'`
Vite配置中 `TanStackRouterVite` 在 `react()` 之后	插件必须在Vite配置中 `react()` 之前加载
`strict: false` 时参数未被解析	使用严格模式，或在导航后手动解析参数
无路径路由的 `notFoundComponent` 无效	改为在子路由上定义 `notFoundComponent`
加载器中止时出现undefined错误	在 `errorComponent` 中添加 `if (!error) return null` 判断
未声明 `loaderDeps`	声明依赖项，使加载器仅在依赖变化时重新运行

Delegation

References

参考资料

Setup — installation, Vite config, file structure, app setup, router default options
Type Safety — register router,
```
from
```
param,
```
strict: false
```
, type utilities, getRouteApi
Data Loading — route loaders, Query integration, parallel loading, streaming, deferred data, abort signal, loaderDeps
Search Params — validation, strip/retain middleware, fine-grained subscriptions, debounce, custom serializers
Navigation — Link, active styling, relative navigation, hash, route masks, blocker, scroll restoration
Auth and Context — beforeLoad, context inheritance, pathless layouts, dependency injection, error handling
Code Splitting — lazy routes, auto splitting, preloading strategies, programmatic preloading
Virtual File Routes — rootRoute, route, index, layout, physical builders, mixing file-based and code-based routing
Known Issues — 20 documented issues with fixes, anti-patterns
Loader+Query Patterns — ensureQueryData in loaders, parallel loading, critical vs non-critical data, search-param-dependent loaders

搭建指南 — 安装、Vite配置、文件结构、应用搭建、路由默认选项
类型安全 — 注册路由、
```
from
```
参数、
```
strict: false
```
、类型工具、getRouteApi
数据加载 — 路由加载器、Query集成、并行加载、流式加载、延迟数据、中止信号、loaderDeps
搜索参数 — 验证、清除/保留中间件、细粒度订阅、防抖、自定义序列化器
导航 — Link组件、激活状态样式、相对导航、哈希、路由掩码、导航拦截、滚动恢复
认证与上下文 — beforeLoad、上下文继承、无路径布局、依赖注入、错误处理
代码分割 — 懒加载路由、自动分割、预加载策略、编程式预加载
虚拟文件路由 — rootRoute、路由、索引、布局、物理构建器、混合基于文件和代码的路由
已知问题 — 20个已记录的问题及修复方案、反模式
加载器+Query模式 — 在加载器中使用ensureQueryData、并行加载、关键与非关键数据、依赖搜索参数的加载器

tanstack-router

Original

Translation

TanStack Router

TanStack Router

Quick Reference

速查参考

Data Loading

数据加载

Preloading

预加载

File Organization

文件组织

Common Mistakes

常见错误

Delegation

相关技能委托

References

参考资料