tanstack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Developer Guide

TanStack开发者指南

This SKILL.md is a dispatcher, not an encyclopedia. The load-bearing detail (code patterns, anti-patterns, edge cases, full checklists) lives in

references/*.md

. The tripwires below exist so you can detect violations during scanning — they are not the contract.

本SKILL.md是一个调度文档，而非百科全书。核心细节（代码模式、反模式、边缘案例、完整检查清单）存于

references/*.md

中。以下注意事项用于在扫描时识别违规情况——它们并非正式规范。

Required Reading Router

必读路由指南

Match the task to the row. Read the listed file(s) in full before producing output. They are not appendices — they are the contract. Inline content in this SKILL.md is a pointer, not a substitute.

Task	MUST read
`useQuery` / `useMutation` / prefetch / infinite list / SSR hydration / cache config	`references/query-patterns.md`
Typed collections, live queries, optimistic collection mutations	`references/db-patterns.md`
Forms, field components, validation, async checks	`references/form-patterns.md`
Routes, search params, loaders, navigation, auth-protected layouts, router setup	`references/router-patterns.md`
Server functions, middleware, sessions, SSR streaming, env, deploy adapters	`references/start-patterns.md`
Anything that touches two or more layers (e.g. route loader + server fn + form)	Each file from the relevant rows — read all before designing

将任务与对应行匹配。在输出内容前务必完整阅读列出的文件。它们不是附录——而是必须遵循的规范。本SKILL.md中的内联内容仅作为指引，不能替代参考文件。

任务	必须阅读的文件
`useQuery` / `useMutation` / 预取 / 无限列表 / SSR 水合 / 缓存配置	`references/query-patterns.md`
类型化集合、实时查询、乐观集合突变	`references/db-patterns.md`
表单、字段组件、验证、异步检查	`references/form-patterns.md`
路由、搜索参数、加载器、导航、受认证保护的布局、路由设置	`references/router-patterns.md`
服务器函数、中间件、会话、SSR 流式传输、环境变量、部署适配器	`references/start-patterns.md`
涉及两个或多个层级的操作（例如路由加载器 + 服务器函数 + 表单）	对应行中的所有文件——设计前需全部阅读

Reference Index

参考索引

File	What you get
`references/query-patterns.md`	Vanilla Query: key factories + `queryOptions` , `staleTime` / `gcTime` , `placeholderData` vs `initialData` , optimistic mutations with rollback, error boundaries, intent prefetch, infinite queries, SSR dehydrate/hydrate, `useQueries` , cancellation, `select` , network mode, persistence, testing
`references/db-patterns.md`	DB collections: 5 critical rules, collection setup, live queries with joins, optimistic updates, shared collection instances, persistence handlers, common anti-patterns, advanced patterns (computed, aggregations, pagination)
`references/form-patterns.md`	Form: `createFormHook` + `useAppForm` , Zod schema validation, field/form/async validators with debounce, reusable field components (TextField, SelectField, SubmitButton), array fields, error handling with a11y, performance, anti-patterns
`references/router-patterns.md`	Router: `declare module` registration, router defaults, `from` narrowing, pathless layouts, search-param Zod validation, parallel + deferred loaders, lazy + auto code splitting, custom serializers, `notFound()` , route masks, integration with TanStack Query
`references/start-patterns.md`	Start: `createServerFn` with Zod validator, request + function middleware, secure cookie sessions, route protection, SSR streaming + hydration safety, prerender/ISR, API routes, env split, file separation, deploy adapters

文件	涵盖内容
`references/query-patterns.md`	基础Query：键工厂 + `queryOptions` 、 `staleTime` / `gcTime` 、 `placeholderData` 与 `initialData` 对比、带回滚的乐观突变、错误边界、意图预取、无限查询、SSR 脱水/水合、 `useQueries` 、取消操作、 `select` 、网络模式、持久化、测试
`references/db-patterns.md`	DB集合：5条关键规则、集合设置、带关联的实时查询、乐观更新、共享集合实例、持久化处理程序、常见反模式、高级模式（计算、聚合、分页）
`references/form-patterns.md`	表单： `createFormHook` + `useAppForm` 、Zod 模式验证、带防抖的字段/表单/异步验证器、可复用字段组件（TextField、SelectField、SubmitButton）、数组字段、无障碍错误处理、性能优化、反模式
`references/router-patterns.md`	Router： `declare module` 注册、路由默认值、 `from` 类型收窄、无路径布局、搜索参数Zod验证、并行+延迟加载器、懒加载+自动代码分割、自定义序列化器、 `notFound()` 、路由掩码、与TanStack Query的集成
`references/start-patterns.md`	Start：带Zod验证器的 `createServerFn` 、请求+函数中间件、安全Cookie会话、路由保护、SSR流式传输+水合安全、预渲染/增量静态再生、API路由、环境变量拆分、文件分离、部署适配器

Tripwires (not the contract)

注意事项（非正式规范）

These bullets exist so you can spot likely violations during a scan. They are deliberately incomplete. The full rules, examples, and edge cases live in the reference files. If a tripwire triggers, you must consult the referenced file before fixing.

这些要点用于在扫描时识别可能的违规情况。它们故意不完整。完整规则、示例和边缘案例请查看参考文件。如果触发了注意事项，修复前必须查阅对应的参考文件。

Query / DB

Vanilla Query and DB collections are different paradigms — never mix them on the same entity.
```
staleTime: 0
```
(default) refetches on every mount. Tune by data volatility.
Optimistic mutations without
```
cancelQueries
```
+ rollback context will get overwritten by in-flight refetches.

STOP. Read
references/query-patterns.md
in full before writing a
useQuery
,
useMutation
, prefetch, or SSR hydration boundary. STOP. Read
references/db-patterns.md
in full before creating a collection, live query, or persistence handler. The three bullets above only flag the most common slip-ups.

基础Query和DB集合是不同的范式——切勿在同一实体上混用。
```
staleTime: 0
```
（默认值）会在每次挂载时重新获取数据。请根据数据的易变性调整。
未搭配
```
cancelQueries
```
+ 回滚上下文的乐观突变会被进行中的重新获取覆盖。

停止操作。在编写
useQuery
、
useMutation
、预取或SSR水合边界前，请完整阅读
references/query-patterns.md
。停止操作。在创建集合、实时查询或持久化处理程序前，请完整阅读
references/db-patterns.md
。以上三个要点仅标记最常见的失误。

Form

```
defaultValues
```
drives type inference — manual generics fight it.
Async validators without
```
asyncDebounceMs
```
hammer the network.
Reuse Zod schemas across form + server function (in
```
*.shared.ts
```
).

STOP. Read
references/form-patterns.md
in full before building or modifying a form, field component, or validator. Field-level a11y attributes,

createFormHook

setup, and array-field patterns are not in this body.

```
defaultValues
```
驱动类型推断——手动泛型会与之冲突。
未设置
```
asyncDebounceMs
```
的异步验证器会频繁请求网络。
在
```
*.shared.ts
```
中复用表单和服务器函数的Zod模式。

停止操作。在构建或修改表单、字段组件或验证器前，请完整阅读
references/form-patterns.md
。字段级无障碍属性、

createFormHook

设置和数组字段模式未包含在本文中。

Router

Without

declare module '@tanstack/react-router' { interface Register { router: typeof router } }

Link

useNavigate

useParams

silently degrade to

unknown

Sequential
```
await
```
s in a loader create waterfalls — fan out with
```
Promise.all
```
.
Throw
```
notFound()
```
/
```
redirect()
```
from loaders, not generic
```
Error
```
.

STOP. Read
references/router-patterns.md
in full before adding a route, changing router setup, writing a loader, or modifying search-param validation. Defaults (

defaultPreload

scrollRestoration

, global error/404), pathless layouts, masks, and deferred loaders all live in the reference.

如果没有

declare module '@tanstack/react-router' { interface Register { router: typeof router } }

，

Link

useNavigate

useParams

会静默降级为

unknown

类型。

加载器中的顺序
```
await
```
会导致请求瀑布——使用
```
Promise.all
```
并行处理。
从加载器中抛出
```
notFound()
```
/
```
redirect()
```
，而非通用
```
Error
```
。

停止操作。在添加路由、修改路由设置、编写加载器或修改搜索参数验证前，请完整阅读
references/router-patterns.md
。默认值（

defaultPreload

、

scrollRestoration

、全局错误/404页面）、无路径布局、掩码和延迟加载器均在参考文件中。

Start

Server logic belongs in
```
createServerFn
```
with a Zod
```
validator()
```
— not raw
```
fetch
```
+ API routes.
Auth uses HTTP-only cookies. localStorage is XSS-bait.
SSR loaders should
```
await
```
only critical data; stream the rest via
```
prefetchQuery
```
+
```
Suspense
```
.

STOP. Read
references/start-patterns.md
in full before writing a server function, middleware, session helper, or SSR loader. Cookie settings, middleware composition order, hydration-safety pitfalls, and adapter trade-offs are not in this body.

服务器逻辑应放在带Zod
```
validator()
```
的
```
createServerFn
```
中——而非原生
```
fetch
```
+ API路由。
认证使用HTTP-only Cookie。localStorage易受XSS攻击。
SSR加载器应仅
```
await
```
关键数据；其余数据通过
```
prefetchQuery
```
+
```
Suspense
```
流式传输。

停止操作。在编写服务器函数、中间件、会话助手或SSR加载器前，请完整阅读
references/start-patterns.md
。 Cookie设置、中间件组合顺序、水合安全陷阱和适配器权衡未包含在本文中。

End-of-task checklist

任务结束检查清单

Each reference file has a scoped checklist with the real validation criteria. This umbrella confirms you actually consulted them:

For each layer you touched, the corresponding reference file was read in full, not skimmed
The scoped checklist in that reference file passes
No mixed Query/DB paradigms on the same entity
```
pnpm run typecheck
```
and
```
pnpm run test
```
pass

If you cannot point to which reference file you read for a given change, the change is not done.

每个参考文件都有一个范围明确的检查清单，包含真正的验证标准。本总清单确认你确实查阅了这些文件：

对于你涉及的每个层级，已完整阅读对应的参考文件，而非略读
该参考文件中的范围检查清单已通过
同一实体上未混用Query/DB范式
```
pnpm run typecheck
```
和
```
pnpm run test
```
执行通过

如果你无法指出针对某一变更所阅读的参考文件，那么该变更未完成。