tanstack-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use this skill when work touches TanStack Query v5, especially

@tanstack/react-query

, server-state caching, query/mutation lifecycle issues, SSR hydration, or migrations from React Query/TanStack Query v4.

当你处理TanStack Query v5相关工作时，尤其是涉及

@tanstack/react-query

、服务端状态缓存、查询/突变生命周期问题、SSR hydration或从React Query/TanStack Query v4迁移的场景，可使用此技能。

Inspect the local Query shape before changing code:
- Package versions for
```
@tanstack/react-query
```
  ,
```
@tanstack/query-core
```
  , devtools, persist/broadcast packages, ESLint plugin, React, framework router, and test utilities.
- Provider setup:
```
QueryClient
```
  ,
```
QueryClientProvider
```
  , SSR request scoping, default options, devtools, and persistence providers.
- Query conventions: query key factories,
```
queryOptions
```
  ,
```
mutationOptions
```
  , custom hooks, router loaders, SSR prefetching, and invalidation helpers.
- Runtime intent: client-only fetching, server prefetch and hydration, route preloading, offline/persistence, or multi-tab sync.
Refresh docs for current behavior, package drift, SSR, persistence, or migrations. Start from source-map.md.
For installation, provider setup, defaults, query keys,
```
useQuery
```
, and TypeScript options, use setup-core.md.
For dependent, parallel, paginated, infinite, disabled, cancellable, selected, and performance-sensitive queries, use query-patterns.md.
For
```
useMutation
```
, invalidation, direct cache writes, optimistic updates, mutation scopes, and offline mutations, use mutations-cache.md.
For prefetching, router integration, SSR, hydration, Suspense, Server Components, and streaming caveats, use ssr-prefetching.md.
For persistence, broadcast sync, devtools, ESLint, testing, and migration checks, use production-tooling.md.

Treat TanStack Query as server-state management, not a replacement for local client UI state.
Query keys are cache identity. Include every changing variable used by the query function, and keep keys serializable.
Prefer object syntax everywhere in v5. Do not reintroduce positional v3/v4 signatures.
Prefer typed
```
queryOptions
```
and
```
mutationOptions
```
helpers for reusable queries and mutations.
Set
```
staleTime
```
deliberately. Default stale data refetches on mount, window focus, and reconnect can be correct, but noisy when misunderstood.
Use targeted invalidation as the default after mutations. Use immutable
```
setQueryData
```
when the mutation response already contains the exact updated object.
For optimistic updates, prefer UI-level
```
variables
```
when only one surface needs the pending state; use cache-level
```
onMutate
```
rollback when multiple surfaces must react.
In SSR, create request-scoped query clients on the server and a stable browser client. Avoid module-level server caches that leak data across users.
In tests, isolate each test with its own
```
QueryClient
```
, turn retries off, and clear or recreate clients rather than sharing cache state.

将TanStack Query视为服务端状态管理工具，而非本地客户端UI状态的替代方案。
查询键是缓存的标识。需包含查询函数使用的所有可变变量，并保持键可序列化。
在v5中优先使用对象语法。不要重新引入v3/v4的位置参数签名。
对于可复用的查询和突变，优先使用带类型的
```
queryOptions
```
和
```
mutationOptions
```
助手。
谨慎设置
```
staleTime
```
。默认的 stale 数据在挂载、窗口聚焦和重新连接时重新获取可能是正确的，但如果不理解其逻辑会产生不必要的请求。
突变后默认使用针对性的失效处理。当突变响应已包含精确的更新对象时，使用不可变的
```
setQueryData
```
。
对于乐观更新，当仅单个界面需要待处理状态时，优先使用UI层面的
```
variables
```
；当多个界面必须做出响应时，使用缓存层面的
```
onMutate
```
回滚。
在SSR中，在服务端创建请求作用域的查询客户端，并使用稳定的浏览器客户端。避免使用模块级别的服务端缓存，以免在用户之间泄露数据。
在测试中，为每个测试单独创建
```
QueryClient
```
，关闭重试机制，清除或重新创建客户端而非共享缓存状态。

Prefer the repo's existing checks. For meaningful TanStack Query changes, include the relevant subset:

Typecheck for query keys, query function returns,
```
select
```
, mutation variables, and SSR hydration types.
Focused tests for invalidation, optimistic rollback, cache updates, dependent queries, pagination, infinite queries, and error states.
Browser smoke for loading, stale-data, background-fetching, pagination, mutation pending/error, hydration, and focus/reconnect behavior.
SSR or route-loader smoke when changing prefetching, hydration, stale times, or provider placement.
ESLint Query plugin checks when the repo uses
```
@tanstack/eslint-plugin-query
```
.

优先使用仓库现有的检查机制。对于重要的TanStack Query变更，需包含以下相关子集：