TanStack ecosystem: judgement layer
This skill holds cross-library rules and pitfalls. API detail comes from the installed versions, so confirm them first. Project conventions win over this file.
Version-matched API first
Read the lockfile and installed declarations before using an API. Consult the
version notes and
version-matched documentation. Flag unrelated
migration sites for deliver.
Where agents slip
- Incomplete keys: the key holds every value the
queryFnreads. - Duplicated query contracts: one
queryOptionsfactory per resource, reused by hook, loader, prefetch and cache reads. - Failed requests that resolve:
fetchresolves on 4xx and 5xx. ThequeryFnthrows for them and forwardssignal. - Status:
isPendingmeans no data and no error yet (a failed first fetch is not pending);isFetchingis a running request. List key changes useplaceholderData: keepPreviousData. - Freshness: choose
staleTimefrom the data; never disable focus refetching to hide a bad value. In Query versions supportingstatic, static observers do not refetch on invalidation; verify with a trace. - Tracked results: destructure only fields read; no rest-spread.
- Optimistic updates: show
variablesbefore editing the cache; money is never optimistic. See references/mutations.md. - Query data is not component state: derive or use
select, never copy touseState. skipToken:refetch()cannot run that query.useSuspenseQuery: noenabledorplaceholderData.
Routing by library
- Imperative Query migration: query methods.
- Form and Store API migrations: form and store.
- Router loaders with Query: router integration.
- Tables and virtual rows: table. Never ship
stockFeatures. Server tables set themanual*options and hold state in the query key. Virtualise only hundreds of rendered rows. - Debounce, throttle, queue: pacer (beta).
- File routes, router-plugin, Hotkeys and Devtools: load the Intent skills
shipped with the installed packages (
router-corechildren,router-plugin,hotkeys-core,devtools-production). Keep devtools dev-only and tree-shaken from production; check the bundle only if that lane may run the project's own build. Devtools packages need compatible versions, per their peer ranges. - Collections and live queries: db (experimental). Charts: use version-matched docs; no reference here.
Verification
Support cache freshness and invalidation claims with a request trace or a focused component test. Record the evidence path.
Test public hooks/components with a fresh QueryClient and retry: false.
Suggest missing Query ESLint rules; never add them unasked. See
verification.