tanstack

TanStack

阅读与要更改的 API 或行为相匹配的参考文档。仅在更改涉及相关问题时才加载相邻参考文档；重用已阅读的相关上下文。

分支

当你要……	参考文档
定义或更改查询键／工厂	references/query-keys.md
设置 staleTime、gcTime、失效、占位数据／初始数据	references/query-caching.md
编写变更、乐观更新或变更状态	references/query-mutations.md
预取、并行查询、无限查询或取消	references/query-fetch-patterns.md
SSR 脱水／水合、离线 networkMode 或查询持久化	references/query-ssr-offline.md
查询错误边界或 select／性能	references/query-errors-performance.md
注册路由器、from 类型、虚拟路由或路由器默认值	references/router-type-and-org.md
路由加载器、ensureQueryData 或并行路由加载	references/router-data-loading.md
搜索参数、Link／navigate、路由遮罩或预加载	references/router-search-nav.md
懒加载路由、未找到页面、路由上下文或 auth beforeLoad	references/router-split-errors-context.md
TanStack Form 钩子、Zod 验证器或字段组件	references/form.md

应用与更改行为相关的技术规则。

注意事项

Query — 数组键应包含所有依赖项；通过规范键协调变更：根据权威响应更新，或在所属读取模型需要重新从服务器读取时使其失效；乐观缓存写入需要回滚；绝不要在键中放入不可序列化的值。

Router — 注册路由器类型；使用默认值验证搜索参数（.catch()）；与 Query 配合时，在加载器中使用 ensureQueryData；使用 throw redirect(...)，而不是 return。

Form — 完整设置 defaultValues 以便推断类型；在表单／字段级别使用 Zod；根据端点成本和交互需求，对异步验证器进行防抖；字段错误使用 role="alert"；提交时调用 preventDefault。