{"schemaVersion":3,"generatedAt":"2026-08-06T09:56:36.585Z","locales":[{"localeId":"zh-cn","languageTag":"zh-CN"},{"localeId":"en","languageTag":"en"}],"discovery":{"llmsUrl":"https://tanstack-atlas.vercel.app/llms.txt","searchUrlTemplate":"https://tanstack-atlas.vercel.app/agents/search.json?locale={localeId}&q={query}","graphUrlTemplate":"https://tanstack-atlas.vercel.app/agents/graph.json?locale={localeId}","ecosystemCatalogUrl":"https://tanstack-atlas.vercel.app/ecosystem/catalog.json","contentManifestUrl":"https://tanstack-atlas.vercel.app/content/manifest.json"},"documents":[{"id":"router.file-route","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-route","read-path-param","file-based-routing"],"contract":{"useWhen":"项目使用 TanStack Router 文件路由，并需要让 URL 路径标识单个资源。","avoidWhen":"不要用于可选筛选条件；这类状态应使用经过验证的 search 参数。","preconditions":"先确认路由目录约定、生成插件以及目标参数名称，禁止手改生成的路由树。","verification":"运行路由生成与类型检查，再直接刷新一个真实参数 URL；Link 参数拼错时必须产生类型错误。","failureMode":"若参数为 undefined，通常是文件名、Route 路径或 Link 参数键不一致；对照生成路由树，而不是强制断言。","security":"路径参数只提供类型化字符串，不代表资源授权；在服务端数据边界重新校验身份与权限。"},"title":"创建带路径参数的文件路由","summary":"在 React 应用中创建 /posts/$postId，并从路由实例读取类型安全的 postId。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/file-route.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/file-route","sourceRefs":["https://tanstack.com/router/latest/docs/routing/file-based-routing"]},{"id":"router.file-route","localeId":"en","languageTag":"en","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-route","read-path-param","file-based-routing"],"contract":{"useWhen":"Use when a file-routed TanStack Router app identifies one resource in the URL path.","avoidWhen":"Do not use for optional filters; validated search params own that state.","preconditions":"Confirm the route-directory convention, generator plugin, and parameter name; never edit the generated route tree.","verification":"Generate routes, typecheck, and refresh a real parameter URL; a misspelled Link param must fail typecheck.","failureMode":"An undefined param usually means the filename, Route path, and Link param key disagree; inspect the generated tree instead of asserting.","security":"A typed path string is not authorization; re-check identity and resource access at the server data boundary."},"title":"Create a file route with a path parameter","summary":"Create /posts/$postId in a React app and read the typed postId from the route instance.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/file-route.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/file-route","sourceRefs":["https://tanstack.com/router/latest/docs/routing/file-based-routing"]},{"id":"router.validated-search","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["validate-search-params","pagination","url-state"],"contract":{"useWhen":"筛选、排序、分页或可分享视图需要由 URL 持有。","avoidWhen":"不要存放秘密、临时输入或无法安全序列化的大对象。","preconditions":"定义允许的键、运行时验证规则、默认值以及规范化后的 URL 形态。","verification":"测试有效、缺失和非法值；刷新、后退与分享链接都必须恢复相同视图。","failureMode":"若一次更新清空其他键，检查 search 更新函数是否基于 previous 合并，而不是创建不完整对象。","security":"URL 输入不可信；验证通过仍不代表可以直接拼接 SQL、文件路径或外部请求。"},"title":"验证分页与筛选参数","summary":"将不可信的 URL 搜索参数转换为稳定、有类型的路由输入。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/validated-search.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/validated-search","sourceRefs":["https://tanstack.com/router/latest/docs/guide/search-params"]},{"id":"router.validated-search","localeId":"en","languageTag":"en","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["validate-search-params","pagination","url-state"],"contract":{"useWhen":"Use for filters, sorting, pagination, or shareable view state owned by the URL.","avoidWhen":"Do not store secrets, transient input, or large values that cannot be safely serialized.","preconditions":"Define allowed keys, runtime validation, defaults, and the canonical serialized URL shape.","verification":"Test valid, missing, and malformed values; refresh, back, and shared links must restore the same view.","failureMode":"If an update clears other keys, verify the search updater merges from previous state instead of returning a partial object.","security":"URL input is untrusted; successful parsing does not make it safe for SQL, file paths, or outbound requests."},"title":"Validate pagination and filter search params","summary":"Turn untrusted URL search params into stable, typed route input.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/validated-search.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/validated-search","sourceRefs":["https://tanstack.com/router/latest/docs/guide/search-params"]},{"id":"start.server-function","localeId":"zh-cn","languageTag":"zh-CN","product":"start","kind":"recipe","framework":"react","packages":["@tanstack/react-start"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-start@1.168.34","revision":3,"sourceCheckedOn":"2026-08-03","tasks":["create-server-function","server-only-code","rpc"],"contract":{"useWhen":"应用内部需要类型安全地调用数据库、秘密或其他仅服务端能力。","avoidWhen":"外部系统、Webhook 或跨域客户端需要调用时，改用 Server Route。","preconditions":"选择 GET 或 POST，定义运行时 validator，并将底层服务端实现隔离在 server-only 文件。","verification":"分别测试合法与非法输入，检查客户端产物不含秘密或数据库实现，并验证调用结果可序列化。","failureMode":"TypeScript 类型不能替代网络边界验证；若非法负载进入 handler，说明缺少或错误配置 validator。","security":"每个处理器都要自行鉴权和授权；不要把路由可见性当成服务端权限边界。"},"title":"创建只在服务端执行的函数","summary":"使用 createServerFn 定义同源、类型安全的服务端 RPC。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/server-function.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/server-function","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"start.server-function","localeId":"en","languageTag":"en","product":"start","kind":"recipe","framework":"react","packages":["@tanstack/react-start"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-start@1.168.34","revision":3,"sourceCheckedOn":"2026-08-03","tasks":["create-server-function","server-only-code","rpc"],"contract":{"useWhen":"Use for app-internal, type-safe calls to databases, secrets, or other server-only capabilities.","avoidWhen":"Use a Server Route instead for external systems, webhooks, or cross-origin clients.","preconditions":"Choose GET or POST, define a runtime validator, and isolate implementation details in a server-only file.","verification":"Test valid and invalid input, confirm client output excludes secrets and database code, and verify the result is serializable.","failureMode":"TypeScript does not validate network input; malformed data reaching the handler indicates a missing or incorrect validator.","security":"Authenticate and authorize inside every handler; route visibility is not a server authorization boundary."},"title":"Create a server-only function","summary":"Use createServerFn to define a same-origin, type-safe server RPC.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/start/server-function.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/start/server-function","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"query.router-or-query","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"decision","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["choose-loader","choose-query","data-loading"],"contract":{"useWhen":"需要决定数据由路由生命周期直接拥有，还是进入具有独立缓存生命周期的 Query。","avoidWhen":"不要用这项决策处理纯客户端 UI 状态；它既不属于 Loader，也不属于 Query。","preconditions":"记录数据是否跨路由复用，以及是否需要失效、轮询、重试或乐观更新。","verification":"输出明确的所有者、缓存策略和重新获取触发点；如果组合使用，必须共享一份 queryOptions。","failureMode":"重复请求通常来自 Loader 和组件各自维护不同 Key 或请求实现；先统一契约再调整 staleTime。","security":"两种加载方式都可能触达服务端数据；数据源必须独立执行权限检查。"},"title":"Router Loader 还是 Query？","summary":"根据导航关键性和数据生命周期选择 Loader、Query 或两者组合。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/router-loader-or-query.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/router-loader-or-query","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query","https://tanstack.com/query/latest/docs/framework/react/overview"]},{"id":"query.router-or-query","localeId":"en","languageTag":"en","product":"query","kind":"decision","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["choose-loader","choose-query","data-loading"],"contract":{"useWhen":"Use when deciding whether route lifecycle or a separately managed Query cache should own remote data.","avoidWhen":"Do not apply this decision to local UI state; it belongs to neither loaders nor Query.","preconditions":"Record whether data is reused across routes and needs invalidation, polling, retries, or optimistic updates.","verification":"State the owner, cache policy, and refetch triggers; if combined, loader and component must share one queryOptions definition.","failureMode":"Duplicate requests often come from separate loader and component keys or fetchers; unify the contract before tuning staleTime.","security":"Both loading paths may reach private server data; authorization belongs at the data source."},"title":"Router loader or Query?","summary":"Choose Loader, Query, or both from navigation criticality and data lifecycle needs.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/router-loader-or-query.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/router-loader-or-query","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query","https://tanstack.com/query/latest/docs/framework/react/overview"]},{"id":"query.loader-prefetch","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router","@tanstack/react-router-ssr-query"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18 + @tanstack/react-router-ssr-query@1.167.1","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["prefetch-query-in-loader","ssr-hydration","avoid-request-waterfall"],"contract":{"useWhen":"目标路由进入前应预热 Query 缓存，并由组件继续观察同一数据。","avoidWhen":"首屏不需要、用户很少访问或成本很高的数据不应无条件阻塞 Loader。","preconditions":"建立共享 queryOptions 工厂，并确保 Loader deps 包含影响 Query Key 的所有路由输入。","verification":"导航期间只触发一个网络请求，组件命中相同缓存；变更参数时产生不同且可预测的 Key。","failureMode":"若组件立即重复请求，比较 Loader 与组件的完整 Query Key、新鲜度和 QueryClient 实例。","security":"预取不会隐藏响应；不要将未经授权的数据放入可序列化缓存或 SSR 负载。"},"title":"在路由 Loader 中预取 Query","summary":"为 SSR 创建请求级 QueryClient，并让 Loader 与 useSuspenseQuery 使用相同 queryOptions。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/loader-prefetch.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/loader-prefetch","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query"]},{"id":"query.loader-prefetch","localeId":"en","languageTag":"en","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router","@tanstack/react-router-ssr-query"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18 + @tanstack/react-router-ssr-query@1.167.1","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["prefetch-query-in-loader","ssr-hydration","avoid-request-waterfall"],"contract":{"useWhen":"Use when a route should warm Query data before entry and the component will observe the same cache entry.","avoidWhen":"Do not block a loader on expensive, rarely visited, or non-critical data.","preconditions":"Create a shared queryOptions factory and include every route input affecting the query key in loader deps.","verification":"Navigation issues one request, the component hits the same cache, and parameter changes create a distinct predictable key.","failureMode":"If the component refetches immediately, compare full query keys, freshness settings, and QueryClient identity.","security":"Prefetching does not hide responses; never place unauthorized data in serialized cache or SSR payloads."},"title":"Prefetch Query from a route loader","summary":"Create a request-scoped QueryClient for SSR and reuse one queryOptions contract in the loader and useSuspenseQuery.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/loader-prefetch.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/loader-prefetch","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query"]},{"id":"query.mutation-cache-update","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-mutation","update-query-cache","invalidate-query"],"contract":{"useWhen":"Mutation 响应包含可信的最新实体，可直接更新精确缓存并减少额外请求。","avoidWhen":"响应不完整或会影响未知列表集合时，优先做有界失效而不是猜测所有缓存形态。","preconditions":"列出受影响 Query Key、服务端响应类型以及失败时应保留的旧值。","verification":"成功后详情与列表一致，失败后旧缓存不变；检查没有无关 Query 被失效。","failureMode":"若列表与详情分叉，响应只写入了一处或 Key 不一致；集中 Key 工厂并明确更新范围。","security":"客户端缓存更新不代表写入成功或已授权；仅使用服务端确认后的响应。"},"title":"用 Mutation 响应更新缓存","summary":"当写入响应包含完整实体时用 setQueryData；无法推导正确缓存时改用 invalidateQueries。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/mutation-cache-update.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/mutation-cache-update","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/mutations","https://tanstack.com/query/latest/docs/framework/react/guides/updates-from-mutation-responses","https://tanstack.com/query/latest/docs/framework/react/guides/invalidations-from-mutations"]},{"id":"query.mutation-cache-update","localeId":"en","languageTag":"en","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-mutation","update-query-cache","invalidate-query"],"contract":{"useWhen":"Use when a mutation returns the authoritative current entity and can update an exact cache entry.","avoidWhen":"Prefer bounded invalidation when the response is partial or affects an unknown set of lists.","preconditions":"List affected query keys, the server response type, and the old value that must survive failure.","verification":"After success, detail and list agree; after failure, old cache remains and unrelated queries are not invalidated.","failureMode":"Divergent list and detail data indicates one cache was skipped or keys differ; centralize key factories and update scope.","security":"A client cache write is not proof of persistence or authorization; use server-confirmed responses only."},"title":"Update cache from a mutation response","summary":"Use setQueryData when the write response contains the complete entity; invalidate when the correct cache cannot be derived.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/mutation-cache-update.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/mutation-cache-update","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/mutations","https://tanstack.com/query/latest/docs/framework/react/guides/updates-from-mutation-responses","https://tanstack.com/query/latest/docs/framework/react/guides/invalidations-from-mutations"]},{"id":"router.route-error-boundary","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"error","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["handle-loader-error","route-error-component","retry-route"],"contract":{"useWhen":"一个路由的 Loader 或渲染失败应被局部隔离并提供恢复动作。","avoidWhen":"不要用通用 errorComponent 表示预期的 404 或重定向。","preconditions":"区分 not found、redirect、可重试错误和未知异常，并确定最近的恢复边界。","verification":"逐一触发 Loader 和组件错误，确认兄弟路由可用、重试会重置状态、未知错误仍可观测。","failureMode":"重试后仍显示旧错误通常表示只重新执行请求而未重置 Router 错误状态。","security":"面向用户的错误不得泄漏堆栈、秘密、数据库信息或内部响应体。"},"title":"隔离路由 Loader 与渲染错误","summary":"为全局 Router 设置默认错误组件，并在需要独立恢复的路由上覆盖 errorComponent。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/route-error-boundary.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/route-error-boundary","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/error-boundaries"]},{"id":"router.route-error-boundary","localeId":"en","languageTag":"en","product":"router","kind":"error","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["handle-loader-error","route-error-component","retry-route"],"contract":{"useWhen":"Use when loader or render failures should be isolated to one route with a recovery action.","avoidWhen":"Do not use a generic errorComponent for expected not-found or redirect control flow.","preconditions":"Classify not found, redirect, retryable failure, and unknown exception, then choose the nearest recovery boundary.","verification":"Trigger loader and component failures; sibling routes stay usable, retry resets state, and unknown errors remain observable.","failureMode":"A stale error after retry usually means the request reran without resetting Router error state.","security":"User-facing errors must not expose stacks, secrets, database details, or internal response bodies."},"title":"Contain route loader and render errors","summary":"Set a Router-wide default and override errorComponent on routes that need independent recovery.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/route-error-boundary.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/route-error-boundary","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/error-boundaries"]},{"id":"start.server-route","localeId":"zh-cn","languageTag":"zh-CN","product":"start","kind":"recipe","framework":"react","packages":["@tanstack/react-start","@tanstack/react-router"],"versionRange":"Start ^1 / Router ^1","verifiedAgainst":"@tanstack/react-start@1.168.34 + @tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-server-route","external-api","return-http-status","choose-server-route"],"contract":{"useWhen":"Webhook、外部客户端或标准 HTTP 集成需要稳定端点。","avoidWhen":"仅供同一 Start 应用内部调用且需要端到端类型时，优先 Server Function。","preconditions":"定义方法、路径、输入、状态码、响应 Schema、鉴权方式和幂等要求。","verification":"用独立 HTTP 客户端测试成功、无权限、非法输入和未找到响应。","failureMode":"外部调用出现 HTML 或 200 错误体时，检查是否显式返回 Response、状态码和 Content-Type。","security":"外部入口必须验证身份、授权、输入大小与重放风险；不要依赖浏览器同源保护。"},"title":"创建外部可调用的 Server Route","summary":"为第三方调用方建立原生 HTTP 端点，并显式返回状态、缓存和安全响应。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/server-route.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/server-route","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/server-routes","https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"start.server-route","localeId":"en","languageTag":"en","product":"start","kind":"recipe","framework":"react","packages":["@tanstack/react-start","@tanstack/react-router"],"versionRange":"Start ^1 / Router ^1","verifiedAgainst":"@tanstack/react-start@1.168.34 + @tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-server-route","external-api","return-http-status","choose-server-route"],"contract":{"useWhen":"Use for webhooks, external clients, or integrations requiring a standard HTTP endpoint.","avoidWhen":"Prefer a Server Function for app-internal calls that need end-to-end types.","preconditions":"Define method, path, input, status codes, response schema, authentication, and idempotency requirements.","verification":"Use an independent HTTP client to test success, unauthorized, invalid-input, and not-found responses.","failureMode":"HTML or 200 error payloads indicate missing explicit Response status and Content-Type handling.","security":"External endpoints must handle identity, authorization, input size, and replay risk without relying on browser same-origin behavior."},"title":"Create an externally callable Server Route","summary":"Build a native HTTP endpoint for third-party callers with explicit status, caching, and safe responses.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/start/server-route.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/start/server-route","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/server-routes","https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"router.typed-context","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"contract","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["inject-router-dependency","augment-route-context","before-load-context"],"contract":{"useWhen":"Loader、beforeLoad 和路由组件需要共享 QueryClient、认证读取器或其他应用级依赖。","avoidWhen":"不要把频繁变化的页面状态或只属于单个组件的数据塞入 Router Context。","preconditions":"通过注册类型定义最小接口，并确定依赖在 RouterProvider 外部如何取得。","verification":"缺少必需依赖时编译失败，父级 beforeLoad 扩展的 Context 在子路由中保持准确类型。","failureMode":"Context 变成 any 通常来自缺少模块注册或在创建 Router 时做了强制断言。","security":"Context 可帮助传递鉴权能力，但不能把客户端认证状态视为服务端授权证据。"},"title":"建立类型化 Router Context","summary":"在根路由声明依赖，并通过 beforeLoad 为子树追加可推导的派生上下文。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/typed-router-context.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/typed-router-context","sourceRefs":["https://tanstack.com/router/latest/docs/guide/router-context","https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes"]},{"id":"router.typed-context","localeId":"en","languageTag":"en","product":"router","kind":"contract","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["inject-router-dependency","augment-route-context","before-load-context"],"contract":{"useWhen":"Use when loaders, beforeLoad, and route components share QueryClient, auth readers, or other app dependencies.","avoidWhen":"Do not put frequently changing page state or component-local data in Router Context.","preconditions":"Register the smallest dependency interface and decide how the value is obtained outside RouterProvider.","verification":"Missing required dependencies fail compilation and context extended by parent beforeLoad remains typed in children.","failureMode":"Context becoming any usually comes from missing module registration or a cast at router creation.","security":"Context can carry auth capabilities, but client auth state is not server authorization evidence."},"title":"Establish typed Router Context","summary":"Declare dependencies at the root and use beforeLoad to add inferred derived context to a subtree.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/typed-router-context.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/typed-router-context","sourceRefs":["https://tanstack.com/router/latest/docs/guide/router-context","https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes"]},{"id":"query.freshness-policy","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["configure-stale-time","configure-gc-time","share-query-options"],"contract":{"useWhen":"团队需要为不同数据类型明确何时新鲜、何时后台更新、何时回收。","avoidWhen":"不要为掩盖错误 Query Key 或重复 QueryClient 而随意提高 staleTime。","preconditions":"记录数据变化频率、允许陈旧时间、主动失效事件和离线需求。","verification":"用可控时间验证 fresh、stale 和 inactive 转换，并测试聚焦与重连后的行为。","failureMode":"意外重新请求先检查默认 stale 状态和聚焦触发；数据不更新再检查是否误用了 static 策略。","security":"注销或权限变化时清理用户作用域缓存，避免在共享浏览器会话中显示前一用户数据。"},"title":"定义 Query 新鲜度契约","summary":"根据数据变化频率设置 staleTime，并独立决定 inactive 缓存的 gcTime。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/freshness-policy.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/freshness-policy","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults","https://tanstack.com/query/latest/docs/framework/react/guides/query-options"]},{"id":"query.freshness-policy","localeId":"en","languageTag":"en","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["configure-stale-time","configure-gc-time","share-query-options"],"contract":{"useWhen":"Use when a team needs explicit freshness, background-refetch, and collection rules for each data type.","avoidWhen":"Do not inflate staleTime to hide incorrect query keys or duplicate QueryClient instances.","preconditions":"Record change frequency, acceptable staleness, explicit invalidation events, and offline needs.","verification":"Use controlled time to verify fresh, stale, and inactive transitions, including focus and reconnect behavior.","failureMode":"For unexpected refetches inspect default staleness and focus triggers; for frozen data check accidental static policy.","security":"Clear user-scoped cache on logout or permission changes to avoid showing previous-user data in shared sessions."},"title":"Define a Query freshness contract","summary":"Set staleTime from data volatility and decide inactive-cache gcTime independently.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/freshness-policy.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/freshness-policy","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults","https://tanstack.com/query/latest/docs/framework/react/guides/query-options"]},{"id":"start.middleware-chain","localeId":"zh-cn","languageTag":"zh-CN","product":"start","kind":"contract","framework":"react","packages":["@tanstack/react-start"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-start@1.168.34","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-middleware","compose-server-function-middleware","choose-middleware-scope"],"contract":{"useWhen":"多个 Server Function、Server Route 或请求需要共享日志、认证、Context 或计时逻辑。","avoidWhen":"只服务一个处理器且没有复用价值的业务逻辑应留在处理器或领域服务中。","preconditions":"确定 Middleware 类型、执行顺序、Context 输入输出以及 next() 的错误传播方式。","verification":"测试顺序、短路、错误和并发请求，确认每个请求的 Context 相互隔离。","failureMode":"处理器未执行或 Context 丢失通常是 next() 未返回、顺序错误或 Middleware 类型不匹配。","security":"日志 Middleware 应主动移除 cookie、Authorization、秘密和敏感请求体。"},"title":"建立 Start Middleware 执行链","summary":"明确请求级与函数级作用域，通过 next() 组合上下文，并保留认证和 CSRF 边界。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/middleware-chain.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/start/middleware-chain","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/middleware","https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"start.middleware-chain","localeId":"en","languageTag":"en","product":"start","kind":"contract","framework":"react","packages":["@tanstack/react-start"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-start@1.168.34","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["create-middleware","compose-server-function-middleware","choose-middleware-scope"],"contract":{"useWhen":"Use when server functions, routes, or requests share logging, auth, context, or timing behavior.","avoidWhen":"Keep one-off business logic in its handler or domain service when it has no cross-cutting reuse.","preconditions":"Choose middleware type, order, context input/output, and how next() propagates errors.","verification":"Test ordering, short-circuiting, errors, and concurrent requests to ensure per-request context isolation.","failureMode":"A skipped handler or missing context usually means next() was not returned, ordering is wrong, or middleware type mismatches.","security":"Logging middleware must redact cookies, Authorization, secrets, and sensitive request bodies."},"title":"Establish a Start Middleware chain","summary":"Define request and function scopes, compose context through next(), and preserve authentication and CSRF boundaries.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/start/middleware-chain.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/start/middleware-chain","sourceRefs":["https://tanstack.com/start/latest/docs/framework/react/guide/middleware","https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"]},{"id":"router.navigation-blocker","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["block-navigation","protect-dirty-form","confirm-route-leave"],"contract":{"useWhen":"离开当前路由会丢失明确可检测的未保存用户输入。","avoidWhen":"不要阻止只会丢失可重新获取数据或无价值临时 UI 状态的导航。","preconditions":"定义可靠的 isDirty、保存成功后的重置动作，以及浏览器卸载策略。","verification":"覆盖 Link、前进后退、刷新、关闭标签页和保存后离开；未修改状态不得出现提示。","failureMode":"保存后仍提示通常表示 Mutation 成功路径没有同步重置 dirty 状态。","security":"阻止导航只能保护体验，不能作为持久化、草稿恢复或并发写入控制。"},"title":"保护脏表单的离页导航","summary":"用 useBlocker 的 resolver 状态实现可访问的离页确认，并按脏状态注册 beforeunload。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/navigation-blocker.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/navigation-blocker","sourceRefs":["https://tanstack.com/router/latest/docs/guide/navigation-blocking"]},{"id":"router.navigation-blocker","localeId":"en","languageTag":"en","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["block-navigation","protect-dirty-form","confirm-route-leave"],"contract":{"useWhen":"Use when leaving the current route would discard explicitly detectable unsaved user input.","avoidWhen":"Do not block navigation for refetchable data or disposable UI state.","preconditions":"Define reliable isDirty state, reset behavior after save, and a browser-unload policy.","verification":"Cover Link, history, refresh, tab close, and post-save leave; pristine state must never prompt.","failureMode":"A prompt after successful save usually means the mutation success path did not reset dirty state.","security":"Navigation blocking protects experience, not persistence, draft recovery, or concurrent-write control."},"title":"Protect navigation away from a dirty form","summary":"Use useBlocker resolver state for accessible leave confirmation and register beforeunload only while dirty.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/navigation-blocker.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/navigation-blocker","sourceRefs":["https://tanstack.com/router/latest/docs/guide/navigation-blocking"]},{"id":"query.abort-signal","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["cancel-query","consume-abort-signal","stop-obsolete-fetch"],"contract":{"useWhen":"查询可能因路由切换、参数变化或手动操作而过期，底层请求支持 AbortSignal。","avoidWhen":"底层操作不可取消或取消会破坏必须完成的写入时，不要伪造取消语义。","preconditions":"确认 queryFn 接收 signal，并把同一实例传给所有相关 I/O。","verification":"在慢请求期间切换参数并观察旧请求中止；缓存应恢复到请求前状态且新请求完成。","failureMode":"网络仍运行说明 signal 未传到底层；空数据成功说明 AbortError 被捕获并转换成普通返回值。","security":"取消客户端等待不会撤销服务端已经完成的副作用，因此不要把查询取消当作事务回滚。"},"title":"消费 Query 的 AbortSignal","summary":"将 queryFn signal 传入底层请求，使取消停止 I/O，并保留明确的缓存回滚语义。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/abort-signal.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/abort-signal","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation","https://tanstack.com/query/latest/docs/framework/react/guides/query-functions"]},{"id":"query.abort-signal","localeId":"en","languageTag":"en","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":2,"sourceCheckedOn":"2026-08-03","tasks":["cancel-query","consume-abort-signal","stop-obsolete-fetch"],"contract":{"useWhen":"Use when a query can become obsolete through navigation, parameter changes, or manual cancellation and the transport supports AbortSignal.","avoidWhen":"Do not simulate cancellation for non-cancellable work or writes that must complete atomically.","preconditions":"Confirm queryFn receives signal and forwards the same instance to every related I/O operation.","verification":"Change params during a slow request and observe the old request abort; cache reverts while the new request completes.","failureMode":"Continued network activity means signal was not forwarded; empty success means AbortError was converted into a normal return.","security":"Cancelling client wait does not undo completed server effects, so query cancellation is not transaction rollback."},"title":"Consume Query AbortSignal","summary":"Pass the queryFn signal into the request layer so cancellation stops I/O with explicit cache-revert semantics.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/abort-signal.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/abort-signal","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation","https://tanstack.com/query/latest/docs/framework/react/guides/query-functions"]},{"id":"router.auth-before-load","localeId":"zh-cn","languageTag":"zh-CN","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["protect-route-group","redirect-to-login","preserve-return-url"],"contract":{"useWhen":"一组 Router 页面必须在任何子 Loader 执行前要求有效登录会话。","avoidWhen":"不要把客户端 beforeLoad 当作服务端资源授权，也不要只靠隐藏导航链接。","preconditions":"确认认证状态如何进入类型化 Router Context、私有路由的共同父级以及允许的登录回跳目标。","verification":"测试未登录直达、登录刷新、会话过期和恶意外部回跳，并证明子 Loader 与服务端入口都在各自边界拒绝未授权请求。","failureMode":"若页面先请求私有数据再跳登录，门禁放得太低或异步认证未在父 beforeLoad 中完成；上移到保护子树的最近共同父级。","security":"验证 redirect 目标为本站安全路径，防止开放重定向；所有私有 Server Function、Server Route 和数据源必须重新鉴权与授权。"},"title":"用 beforeLoad 保护路由子树","summary":"在 pathless layout 中读取类型化认证 Context，阻止未登录用户加载子路由，并保留经过约束的回跳 URL。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/auth-before-load.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/router/auth-before-load","sourceRefs":["https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes","https://tanstack.com/router/latest/docs/framework/react/guide/router-context"]},{"id":"router.auth-before-load","localeId":"en","languageTag":"en","product":"router","kind":"recipe","framework":"react","packages":["@tanstack/react-router"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-router@1.170.18","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["protect-route-group","redirect-to-login","preserve-return-url"],"contract":{"useWhen":"Use when a Router subtree requires a valid signed-in session before any child loader runs.","avoidWhen":"Do not treat client beforeLoad as server resource authorization or rely on hidden navigation links.","preconditions":"Identify how auth reaches typed Router Context, the common parent of private routes, and the allowed post-login destinations.","verification":"Test signed-out direct entry, signed-in refresh, session expiry, and a malicious external return URL; prove child loaders and server entries independently reject unauthorized access.","failureMode":"If private data loads before redirect, the gate is too low or async auth was not completed in the parent beforeLoad; move it to the nearest common ancestor.","security":"Validate return targets as safe same-site paths to prevent open redirects; every private Server Function, Server Route, and data source must authenticate and authorize again."},"title":"Protect a route subtree with beforeLoad","summary":"Read typed auth context in a pathless layout, stop signed-out users before child loading, and preserve a constrained return URL.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/router/auth-before-load.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/router/auth-before-load","sourceRefs":["https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes","https://tanstack.com/router/latest/docs/framework/react/guide/router-context"]},{"id":"query.infinite-cursor","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["build-infinite-query","paginate-by-cursor","bound-query-pages"],"contract":{"useWhen":"一个列表需要追加加载页面，并由服务端游标或明确 offset 决定下一页。","avoidWhen":"普通分页需要可分享页码和随机跳页时，优先把 page 放入 URL 并使用常规 Query。","preconditions":"定义 initialPageParam、末页信号、稳定 Query Key、页面响应形状以及是否需要 maxPages 或双向翻页。","verification":"记录连续 pageParam，验证末页、失败重试、筛选切换与重复点击；pages 和 pageParams 必须始终一一对应。","failureMode":"重复页通常来自客户端猜测游标、getNextPageParam 返回旧值或并发触发 fetchNextPage；从网络记录和最后一页响应定位。","security":"游标是外部输入且可能被篡改；服务端必须验证作用域、排序与用户权限，不能把游标当作授权令牌。"},"title":"建立有界的游标 Infinite Query","summary":"用一份 queryKey 管理整个列表，让服务端游标驱动 pageParam，并用 maxPages 控制缓存与重取成本。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/infinite-cursor.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/infinite-cursor","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/infinite-queries","https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery"]},{"id":"query.infinite-cursor","localeId":"en","languageTag":"en","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["build-infinite-query","paginate-by-cursor","bound-query-pages"],"contract":{"useWhen":"Use for a list that appends pages and receives the next cursor or explicit offset from the server contract.","avoidWhen":"Prefer URL page state and a regular Query when pagination needs shareable page numbers or random access.","preconditions":"Define initialPageParam, final-page signal, stable query key, page response shape, and whether maxPages or bidirectional paging is required.","verification":"Record sequential pageParams and test final-page, retry, filter changes, and repeated clicks; pages and pageParams must always correspond.","failureMode":"Duplicate pages usually come from guessed cursors, a stale getNextPageParam result, or concurrent fetchNextPage calls; inspect network records and the last-page response.","security":"Cursors are tamperable external input; the server must validate scope, ordering, and user permissions rather than treating a cursor as authorization."},"title":"Build a bounded cursor Infinite Query","summary":"Use one queryKey for the full list, let server cursors drive pageParam, and bound cache and refetch cost with maxPages.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/infinite-cursor.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/infinite-cursor","sourceRefs":["https://tanstack.com/query/latest/docs/framework/react/guides/infinite-queries","https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery"]},{"id":"query.ssr-streaming","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router","@tanstack/react-router-ssr-query"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18 + @tanstack/react-router-ssr-query@1.167.1","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["configure-query-ssr","stream-query-data","prevent-hydration-refetch"],"contract":{"useWhen":"Router 或 Start 应用要在 SSR 中预取 Query，并自动脱水、恢复或流式发送结果。","avoidWhen":"纯 SPA 或仅客户端数据不需要 SSR 序列化；不要为它们增加服务端恢复复杂度。","preconditions":"确认 getRouter 按请求执行、QueryClient 的所有者、关键与非关键查询分类，以及允许进入浏览器载荷的数据字段。","verification":"用并发用户会话检查缓存隔离，检查 HTML/流载荷不含秘密，并确认 hydrated 查询不会立刻重复请求。","failureMode":"跨请求数据串线说明 QueryClient 被提升成模块单例；hydration 后重复请求通常来自 key、实例或 staleTime 不一致。","security":"脱水缓存对浏览器可见；先授权再查询，只序列化最小字段，并依赖安全转义的官方集成处理 HTML 上下文。"},"title":"配置 Query SSR 与流式恢复","summary":"为每个 SSR 请求创建 QueryClient，通过官方 Router 集成脱水与恢复，并明确阻塞和流式查询。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/ssr-streaming.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/ssr-streaming","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query","https://tanstack.com/query/latest/docs/framework/react/guides/ssr"]},{"id":"query.ssr-streaming","localeId":"en","languageTag":"en","product":"query","kind":"contract","framework":"react","packages":["@tanstack/react-query","@tanstack/react-router","@tanstack/react-router-ssr-query"],"versionRange":"Query ^5 / Router ^1","verifiedAgainst":"@tanstack/react-query@5.101.4 + @tanstack/react-router@1.170.18 + @tanstack/react-router-ssr-query@1.167.1","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["configure-query-ssr","stream-query-data","prevent-hydration-refetch"],"contract":{"useWhen":"Use when a Router or Start app prefetches Query during SSR and needs automatic dehydration, hydration, or streaming.","avoidWhen":"A pure SPA or client-only data does not need SSR serialization; do not add server hydration complexity without value.","preconditions":"Confirm getRouter runs per request, QueryClient ownership, critical versus optional query classes, and the fields allowed in browser payloads.","verification":"Use concurrent user sessions to verify cache isolation, inspect HTML/stream payloads for secrets, and confirm hydrated queries do not immediately refetch.","failureMode":"Cross-request data indicates a module-level QueryClient singleton; an immediate hydration refetch usually means query keys, instances, or staleTime disagree.","security":"Dehydrated cache is browser-visible; authorize before fetching, serialize minimum fields, and rely on the officially escaped integration for HTML context."},"title":"Configure Query SSR and streaming hydration","summary":"Create a QueryClient per SSR request, use the Router integration for dehydration and hydration, and classify blocking versus streaming queries.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/ssr-streaming.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/ssr-streaming","sourceRefs":["https://tanstack.com/router/latest/docs/integrations/query","https://tanstack.com/query/latest/docs/framework/react/guides/ssr"]},{"id":"query.optimistic-rollback","localeId":"zh-cn","languageTag":"zh-CN","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["optimistic-update","rollback-mutation","reconcile-server-state"],"contract":{"useWhen":"写入延迟明显且用户需要即时反馈，同时旧缓存可以准确快照和恢复。","avoidWhen":"复杂权限、服务端排序或跨多列表规则无法在客户端准确重演时，只显示 pending 变量或等待响应。","preconditions":"列出所有受影响 Query Key、快照类型、冲突响应、回滚策略和最终重新验证范围。","verification":"覆盖成功、网络失败、验证错误、409 冲突和并发提交；每条路径最终与服务端一致且无旧 refetch 覆盖新值。","failureMode":"闪回旧值通常是 onMutate 未先等待 cancelQueries；错误后残留草稿说明快照缺失、原地修改或回滚 Key 不一致。","security":"乐观 UI 不证明服务端写入或授权成功；权限拒绝和业务冲突必须回滚，敏感动作不应伪装为已完成。"},"title":"实现可回滚的乐观更新","summary":"取消冲突重取、保存缓存快照、不可变写入草稿，并在失败时回滚、完成时重新验证。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/optimistic-rollback.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/query/optimistic-rollback","sourceRefs":["https://tanstack.com/query/v5/docs/framework/react/guides/optimistic-updates","https://tanstack.com/query/v5/docs/framework/react/guides/mutations"]},{"id":"query.optimistic-rollback","localeId":"en","languageTag":"en","product":"query","kind":"recipe","framework":"react","packages":["@tanstack/react-query"],"versionRange":"^5","verifiedAgainst":"@tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["optimistic-update","rollback-mutation","reconcile-server-state"],"contract":{"useWhen":"Use when mutation latency is noticeable, immediate feedback matters, and old cache can be snapshotted and restored exactly.","avoidWhen":"Show pending variables or wait for the response when complex permissions, server ordering, or multi-list rules cannot be reproduced accurately.","preconditions":"List all affected query keys, snapshot types, conflict responses, rollback policy, and final revalidation scope.","verification":"Cover success, network failure, validation error, conflict, and concurrent submission; every path converges on server state without a stale refetch overwriting the draft.","failureMode":"A flash back to old data usually means onMutate did not await cancelQueries; a draft surviving failure indicates a missing snapshot, in-place mutation, or mismatched rollback key.","security":"Optimistic UI is not proof of persistence or authorization; permission denial and domain conflicts must roll back, and sensitive operations should not appear completed prematurely."},"title":"Implement a rollback-safe optimistic update","summary":"Cancel conflicting refetches, snapshot cache, write an immutable draft, roll back on failure, and revalidate on settlement.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/query/optimistic-rollback.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/query/optimistic-rollback","sourceRefs":["https://tanstack.com/query/v5/docs/framework/react/guides/optimistic-updates","https://tanstack.com/query/v5/docs/framework/react/guides/mutations"]},{"id":"table.server-grid-state","localeId":"zh-cn","languageTag":"zh-CN","product":"table","kind":"contract","framework":"react","packages":["@tanstack/react-table","@tanstack/react-query"],"versionRange":"Table ^8 / Query ^5","verifiedAgainst":"@tanstack/react-table@8.21.3 + @tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["server-side-table","controlled-sorting","manual-pagination","query-key"],"contract":{"useWhen":"表格只持有服务端返回的一页数据，排序与分页必须进入 URL、Query Key 和 API 请求。","avoidWhen":"数据量小且完整存在客户端时，优先使用内置排序与分页行模型，减少远程状态复杂度。","preconditions":"定义可排序列白名单、零基 pageIndex、pageSize 上限、总 rowCount、稳定 Query Key，以及 URL 与 Table 状态的唯一所有者。","verification":"验证排序、翻页、刷新、后退与无结果页；每次状态变化只产生一条正确请求，rowCount 驱动的末页按钮准确禁用。","failureMode":"排序只影响当前页说明误用了 getSortedRowModel；状态完全不动通常是传了 onSortingChange 或 onPaginationChange，却漏掉对应 state 值。","security":"列 id、排序方向、页码和 pageSize 都是外部输入；服务端必须白名单映射列、限制范围、独立鉴权，禁止把列 id 直接拼入 SQL。"},"title":"协调服务端表格的排序与分页状态","summary":"让 Table 管视图状态、Query 管远程数据，并用 manualSorting、manualPagination 与 rowCount 避免只处理当前页。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/table/server-grid-state.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/table/server-grid-state","sourceRefs":["https://tanstack.com/table/latest/docs/framework/react/guide/table-state","https://tanstack.com/table/latest/docs/guide/sorting","https://tanstack.com/table/latest/docs/guide/pagination"]},{"id":"table.server-grid-state","localeId":"en","languageTag":"en","product":"table","kind":"contract","framework":"react","packages":["@tanstack/react-table","@tanstack/react-query"],"versionRange":"Table ^8 / Query ^5","verifiedAgainst":"@tanstack/react-table@8.21.3 + @tanstack/react-query@5.101.4","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["server-side-table","controlled-sorting","manual-pagination","query-key"],"contract":{"useWhen":"Use when a table receives one server page and sorting and pagination must flow through URL state, query keys, and the API request.","avoidWhen":"Prefer built-in sorting and pagination row models when the complete, reasonably small dataset is already in the client.","preconditions":"Define sortable-column allowlists, zero-based pageIndex, pageSize bounds, total rowCount, a stable query key, and one owner for URL and Table state.","verification":"Verify sort, pagination, refresh, back navigation, and empty pages; each state change issues one correct request and rowCount disables the final next-page action.","failureMode":"Sorting only the current page indicates an accidental getSortedRowModel; frozen controls usually mean an onSortingChange or onPaginationChange callback lacks its matching state value.","security":"Column ids, sort direction, page, and pageSize are external input; map columns through an allowlist, bound values, authorize independently, and never interpolate column ids into SQL."},"title":"Coordinate sorting and pagination for a server-backed table","summary":"Let Table own view state and Query own remote data, using manualSorting, manualPagination, and rowCount to avoid processing only the current page.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/table/server-grid-state.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/table/server-grid-state","sourceRefs":["https://tanstack.com/table/latest/docs/framework/react/guide/table-state","https://tanstack.com/table/latest/docs/guide/sorting","https://tanstack.com/table/latest/docs/guide/pagination"]},{"id":"form.async-validation","localeId":"zh-cn","languageTag":"zh-CN","product":"form","kind":"contract","framework":"react","packages":["@tanstack/react-form"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-form@1.33.3","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["async-field-validation","debounce","submission-state","server-validation"],"contract":{"useWhen":"字段是否有效依赖服务端事实，例如唯一名称或邀请码，并且需要在最终提交前提供提前反馈。","avoidWhen":"格式、长度和必填等本地规则应同步验证；不要为了“统一”把所有规则都变成网络请求。","preconditions":"先定义同步前置校验、异步触发时机、debounce、规范化规则、请求失败文案，以及提交端的同规则重新校验。","verification":"用假计时器和可控响应测试快速输入、失焦、重复值、网络失败与提交；无效输入不发请求，最终界面只对应当前值。","failureMode":"每次按键都请求通常是 debounce 配置在错误层级；旧值错误覆盖新值时，应检查自定义请求层是否保留了过期响应结果。","security":"提前校验端点可能泄露账号或资源是否存在；对响应做最小化、限速并评估枚举风险，最终提交仍需完整认证、授权与输入校验。"},"title":"为字段异步校验建立安全边界","summary":"先同步过滤无效输入，再用内置 debounce 执行异步校验，并把提前反馈与最终服务端验证明确分开。","markdownUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/form/async-validation.md","htmlUrl":"https://tanstack-atlas.vercel.app/zh-cn/agents/form/async-validation","sourceRefs":["https://tanstack.com/form/latest/docs/framework/react/guides/validation","https://tanstack.com/form/latest/docs/framework/react/guides/submission-handling","https://tanstack.com/form/latest/docs/framework/react/guides/custom-errors"]},{"id":"form.async-validation","localeId":"en","languageTag":"en","product":"form","kind":"contract","framework":"react","packages":["@tanstack/react-form"],"versionRange":"^1","verifiedAgainst":"@tanstack/react-form@1.33.3","revision":1,"sourceCheckedOn":"2026-08-03","tasks":["async-field-validation","debounce","submission-state","server-validation"],"contract":{"useWhen":"Use when field validity depends on server facts such as a unique name or invite code and early feedback is useful before final submission.","avoidWhen":"Keep required, length, and format rules synchronous; do not turn every rule into a network request for uniformity.","preconditions":"Define synchronous guards, async trigger timing, debounce, normalization, network-failure messaging, and equivalent submission-time server validation.","verification":"Use fake timers and controlled responses to test rapid input, blur, duplicate values, network failure, and submit; invalid input sends no request and final UI matches the current value.","failureMode":"A request per keystroke usually means debounce is configured at the wrong level; if an old error overwrites a new value, inspect custom request code for stale response handling.","security":"Preflight validation can reveal account or resource existence; minimize responses, rate-limit, assess enumeration risk, and still authenticate, authorize, and validate the final submission."},"title":"Build a safe boundary for async field validation","summary":"Reject invalid input synchronously, run async validation through built-in debouncing, and separate early feedback from final server validation.","markdownUrl":"https://tanstack-atlas.vercel.app/en/agents/form/async-validation.md","htmlUrl":"https://tanstack-atlas.vercel.app/en/agents/form/async-validation","sourceRefs":["https://tanstack.com/form/latest/docs/framework/react/guides/validation","https://tanstack.com/form/latest/docs/framework/react/guides/submission-handling","https://tanstack.com/form/latest/docs/framework/react/guides/custom-errors"]}]}