TanStack/query
github.com/TanStack/query ↗ · 3553 files · 11.7 MB
Become a Sponsor! TanStack Query An async state management library built to simplify fetching, caching, synchronizing, and updating server state.
Overview
TanStack Query is a TypeScript library for application developers who need to fetch, cache, synchronize, and update asynchronous server state across UI frameworks. Its framework-independent QueryClient, caches, retry machinery, and observers power framework adapters, with optional persistence, hydration, cross-tab synchronization, developer tools, and ESLint rules. This brief investigates commit 29859ae60c8dca0a5cdbf8abccc775b655cf43e2 through bounded source inspection, including concrete startup, fetch, mutation, and persistence flows.
System map
The repository distributes libraries rather than one deployed application. Query-core supplies state ownership and execution primitives; framework packages translate those primitives into framework lifecycle and reactivity. Persistence and broadcast packages introduce optional storage and messaging boundaries, while developer tools observe and manipulate the same caches. The inspected workspace uses pnpm and Nx, with package builds and Changesets publication.
- The root is a private ESM workspace pinned to pnpm@12.4.2; workspace membership includes packages, integrations, and framework examples, with Vue 2 and Nuxt examples excluded.
- Query-core's public entrypoint exports QueryClient, QueryCache, MutationCache, observers, hydration, managers, cancellation types, and experimental_streamedQuery.
- QueryClient creates or accepts QueryCache and MutationCache instances and owns client defaults, key-specific default registries, and lifecycle subscriptions.
- React connects observers through useSyncExternalStore; Vue computes unwrapped options and updates reactive state; Svelte uses runes and observer subscriptions with lifecycle cleanup.
- Runtime caches are in memory: QueryCache constructs a Map keyed by query hash, while MutationCache constructs a mutation Set and a scope-to-mutations Map.
- Network execution is delegated to application queryFn and mutationFn callbacks; the offline example implements fetch requests and MSW handlers outside query-core.
- Root test:pr runs affected Nx checks, test:ci runs checks across projects, and build:all excludes examples and integrations; Nx orders dependency compilation and build targets.
- Published core packages expose ESM, CommonJS, declarations, and source conditions; shared tsdown factories generate modern and legacy bundles, and the release workflow builds before Changesets publication.
Feature catalog
The public product is a family of APIs for server-state management. Inspected features include reactive and imperative queries, mutations, pagination, background refresh, streaming, and server/client hydration. Persistence and cross-tab synchronization are optional integrations. Developer tools and lint rules support application debugging and API usage.
- React exports useQuery, useQueries, Suspense query variants, prefetch hooks, useInfiniteQuery, mutation hooks, activity indicators, providers, and option factories.
- queryClient.query resolves stale data through fetch or returns fresh cached data, then applies optional select; infiniteQuery marks options as infinite and delegates to query.
- Queries support dependent execution through enabled or skipToken, initial data, selected results, and previous-page placeholders through keepPreviousData.
- Background refresh supports mount, focus, reconnect, and interval triggers; interval fetching respects enabled/server checks and focus unless refetchIntervalInBackground is enabled.
- Infinite queries fetch forward or backward using page-parameter callbacks, maintain pages and pageParams together, stop when subsequent parameters are nullish, and bound retained pages through maxPages.
- Mutations expose fire-and-forget mutate and promise-returning mutateAsync, optimistic lifecycle callbacks, and serialization for mutations sharing scope.id.
- Optional state portability includes hydrate/dehydrate, storage-backed cache persistence, cross-tab broadcasts, and streamed AsyncIterable accumulation with reset, append, or replace refetch modes.
- Devtools provides query/mutation views, filtering and sorting state, offline controls, and JSON cache editing; the ESLint plugin provides eight registered rules with recommended and stricter configurations.
Data flow
Keys and options enter through adapters or QueryClient methods and resolve into shared cache entries. Application callbacks produce raw data, while observers derive presentation results and notify framework subscribers. Mutations retain variables and optimistic context separately from query data. Hydration, persistence, and broadcast transfer snapshots across explicit external boundaries.
- defaultQueryOptions merges client query defaults, matching key defaults, and caller options in that order; it computes a missing queryHash and derives reconnect, Suspense-error, persister-network, and skipToken defaults.
- hashQueryKeyByOptions chooses queryKeyHashFn or hashKey; the default hash JSON-stringifies keys with sorted plain-object properties, and QueryCache.build reuses an entry by that hash.
- Query.fetch constructs callback context containing client, queryKey, meta, and a consumed-signal getter; an optional persister wraps queryFn and a behavior hook can replace fetchFn before retry execution.
- Successful fetch data passes through replaceData and a success dispatch; the reducer updates timestamps and status, then notifies a stable observer snapshot and cache subscribers.
- QueryObserver derives placeholder and selected data without replacing raw query state; select results are memoized, selector exceptions become observer errors, and property tracking filters listener notifications.
- MutationObserver.mutate builds a new Mutation for supplied variables; Mutation.execute stores the onMutate result as context and supplies variables, context, and function metadata to lifecycle callbacks.
- persistQueryClientSave packages buster, timestamp, and dehydrated state; the async storage adapter serializes that envelope and writes it through caller-provided storage, while restore reads and deserializes the same key.
- Broadcast sends successful updates, additions, and removals with observers; incoming messages set or build query state inside an echo-suppression transaction, and cleanup unsubscribes and closes the channel.
Behavior traces
The investigation followed startup, primary fetch, optimistic mutation, and persistent restoration through concrete source files. These are source execution traces rather than observed runtime recordings. Each trace retains important conditional branches, including stale-cache reuse, restoration gating, cancellation, and scope queues. The offline example supplies an application-level path connecting these library mechanisms.
- Offline example startup calls worker.start, resolves #root, and renders App; App supplies its configured client and localStorage persister to PersistQueryClientProvider.
- Provider lifecycle runs QueryClientProvider's effect → client.mount → focusManager/onlineManager subscriptions; positive events await resumePausedMutations before notifying the query cache, and the last unmount removes subscriptions.
- React query flow runs useQuery → useBaseQuery → useQueryClient/defaultQueryOptions → new QueryObserver → getOptimisticResult → useSyncExternalStore subscription; restoring or subscribed:false prevents that subscription.
- The first observer subscriber runs addObserver → shouldFetchOnMount → executeFetch → Query.fetch → retryer.start → queryFn; success calls setData → dispatch → observer.onQueryUpdate → updateResult and framework notification.
- Imperative fetch runs queryClient.query → defaultQueryOptions → QueryCache.build → isStaleByTime; stale entries fetch and fresh entries reuse state.data, with retries disabled unless explicitly configured and select applied afterward.
- Comment submission runs Detail.submitForm → updateMovie.mutate → MutationObserver.mutate → Mutation.execute; useMovie.onMutate cancels detail fetches, snapshots old data, and writes optimistic data, with rollback onError and invalidation onSettled.
- Mutation completion awaits global onSuccess → local onSuccess → global onSettled → local onSettled before success dispatch; restored pending mutations skip onMutate, and finally releases the retryer and advances the scope queue.
- Persistent startup runs provider restore → persister.restoreClient → timestamp/maxAge/buster checks → hydrate → awaited onSuccess → isRestoring:false → cache subscriptions; later added/removed/updated events run save → dehydrate → persistClient.
Testing signals
Tests and CI were inspected, not executed; test existence and assertions are not passing results. The inspected suites use Vitest, fake timers, jsdom, React Testing Library, and type assertions. They exercise cache timing, observer transitions, mutation queues, hydration, restoration, and throttling. This inventory is bounded: the sampled tests do not establish production network, storage, browser, or every-adapter coverage.
- Core Vitest configuration searches src, disables watch, uses jsdom, enables typechecking and restored mocks, and enables Istanbul source coverage when CI is set.
- query.test.tsx constructs a mounted client with fake timers and asserts longest-observed gcTime plus retry continuation after visibility restoration using simulated events.
- The mutation scope test submits two mutations with the same scope, asserts the second is paused, and expects start-A/finish-A/start-B/finish-B ordering after advancing timers.
- Hydration tests check Date serialization without mutating cached data, opt-out error redaction for a pending promise, and JSON round trips for multiple serializable data shapes.
- React's successful-query test asserts the complete pending/fetching → success/idle result transition; its configuration uses a React plugin, jsdom, setup files, and three retries in CI.
- PersistQueryClientProvider tests use an in-memory mock persister and assert idle fetching while restoring, hydrated data, and subsequent fetched data; this sampled test does not exercise real localStorage failures.
- Type tests assert tagged-key inference using expectTypeOf, package scripts compile against TS 5.6–5.9, the catalog compiler, and TS 7.0, and asyncThrottle tests assert coalescing and interval timing.
- PR CI starts distributed Nx agents and invokes test:pr; configured targets include lint, runtime/type/package checks and builds, while preview CI separately builds, publishes previews, and checks bundle size. No CI outcome was retrieved or executed.
Risk map
These risks are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. The most consequential boundaries are request-local cache ownership, serialized data, incoming broadcast snapshots, and callback execution. Shared core behavior also has broad adapter impact and several compatibility branches. Release tooling performs privileged external actions and was inspected only as public source.
- SSR documentation explicitly warns that a module-level QueryClient shares cache across requests and can expose sensitive data; request-local client construction is an application integration requirement.
- Hypothesis: persisting sensitive successful query data could expose it through the chosen storage because the default adapter uses JSON serialization and a shared default key; dehydration filters and custom serializers are the available controls. (inferred)
- Restoration checks timestamp age and buster, but hydrate consumes supplied arrays and states without structural schema validation in the inspected implementation; malformed deserialized state can throw and trigger cache removal.
- Broadcast's incoming updated branch directly sets supplied state without comparing update timestamps; this differs from hydrate's newer-data checks and creates a freshness-review hotspot.
- Cancellation depends on signal consumption: removing the last observer cancels and reverts when the signal was consumed or an initial load is paused; otherwise it cancels retries while allowing the current result to cache.
- Mutation success/settled callback exceptions enter the mutation error path even after mutationFn resolves; exceptions from error callbacks are emitted as separate rejected promises, so transport success and reported mutation success can diverge.
- Compatibility is active rather than dead code: deprecated imperative query methods remain, root ESLint restricts new calls, and createSyncStoragePersister is deprecated in favor of the async adapter.
- Release automation has write and OIDC permissions; create-github-release shells out to tag/push and gh release, writes notes outside the repository via tmpdir, and may delete newly created tags on failure.
Extension points
Extensions attach through options, callbacks, subscriptions, adapter primitives, and separate packages. Query and mutation functions are the main transport boundary, while persister contracts provide storage substitution. Manager setters allow environments and frameworks to replace event or scheduling behavior. Typed registration and ESLint rule tables supply compile-time and tooling extension mechanisms.
- Applications supply queryFn and mutationFn; query persisters wrap fetch execution, and QueryBehavior.onFetch can customize fetch context, with infinite queries selecting their built-in behavior.
- setQueryDefaults and setMutationDefaults register options by hashed keys; matching query defaults merge in registration order, so specific defaults should follow generic ones.
- Persister requires persistClient, restoreClient, and removeClient; the async storage factory accepts caller storage, key, throttle interval, serializers, and a retry callback that can transform or discard the snapshot.
- Dehydration supports query/mutation selection, data serialization, and pending-error redaction; hydration accepts deserialization and restored query/mutation defaults.
- focusManager.setEventListener and onlineManager.setEventListener replace environment listeners and clean up prior handlers; callers can also set focus or online state manually.
- createNotifyManager exposes setNotifyFunction, setBatchNotifyFunction, and setScheduler to integrate test wrappers, framework batching, and alternate scheduling.
- The Register interface supports declaration merging for defaultError, queryKey, mutationKey, queryMeta, and mutationMeta through core or adapter modules.
- Framework APIs build on shared observers, with Lit exporting query/mutation controllers and Angular exporting injection/provider features; lint extensions register rule modules in rules.ts and configure presets in index.ts.
Contributor handoff
Tests and CI were inspected, not executed, and this source inventory is bounded rather than exhaustive. Future agents should begin with repository instructions, the owning package, and the relevant core-to-adapter flow. Core edits require attention to cache identity, observer timing, cancellation, mutation callbacks, and external snapshots. Validation commands below are recommendations for a future authorized implementation task, not actions performed during this investigation.
- AGENTS.md requires reading CONTRIBUTING.md before analysis or changes; contribution guidance requires focused changes, understood and verified generated code, and the repository PR template.
- Resolve package-manager drift explicitly: CONTRIBUTING.md mentions pnpm v11, while the pinned root manifest specifies pnpm@12.4.2 and a matching minimum engine.
- Read the runtime owner before adapter changes: useBaseQuery defaults options and owns React subscriptions, QueryObserver decides fetch/result behavior, and QueryClient owns caches and lifecycle listeners.
- Preserve notification-aware writes: setQueryData applies an updater, skips undefined, and writes through Query.setData; direct state-object mutation bypasses QueryCache's documented notifications.
- For authorized validation, run package runtime tests from the root through pnpm nx run @tanstack/{package-name}:test:lib; Nx compiles dependencies first, and package scripts provide separate type and package-export checks.
- Published-package changes require a changeset, while docs, CI, examples, and development-only changes do not; Changesets config places many packages in fixed version groups.
- Reference markdown is generated from source JSDoc, so edit JSDoc rather than generated pages; new documentation pages also require updating docs/config.json.
- Do not assume snapshots preserve executable behavior: dehydrateMutation stores key/state/scope/meta, and the offline example registers a default mutationFn specifically to resume paused mutations after reload.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 1766 | docs/config |
| TypeScript | 991 | 78% |
| JSON | 307 | docs/config |
| JavaScript | 174 | 14% |
| Svelte | 86 | 7% |
| HTML | 78 | docs/config |
| Vue | 20 | 2% |
| CSS | 19 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (946 files)
Repository structure
| Top-level path | Files |
|---|---|
docs/ | 1660 |
packages/ | 946 |
examples/ | 803 |
integrations/ | 102 |
.github/ | 10 |
scripts/ | 7 |
media/ | 2 |
.nx/ | 1 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/community-resources.mddocs/eslint/eslint-plugin-query.mddocs/eslint/exhaustive-deps.mddocs/eslint/infinite-query-property-order.mddocs/eslint/mutation-property-order.mddocs/eslint/no-rest-destructuring.mddocs/eslint/no-unstable-deps.md
Package
package.json — root, 33 declared dependencies.
@arethetypeswrong/cli@changesets/changelog-github@changesets/cli@cspell/eslint-plugin@size-limit/preset-small-lib@tanstack/eslint-config@tanstack/typedoc-config@testing-library/jest-dom@types/node@vitest/coverage-istanbul@vitest/eslint-plugineslint
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsintegrations/svelte-vite/vite.config.js— Vite configintegrations/lit-vite/vite.config.ts— Vite configintegrations/solid-vite/vite.config.js— Vite configintegrations/react-vite/vite.config.js— Vite configintegrations/vue-vite/vite.config.ts— Vite configexamples/svelte/optimistic-updates/vite.config.ts— Vite configexamples/svelte/playground/vite.config.ts— Vite configexamples/svelte/auto-refetching/vite.config.ts— Vite config
Structural health signals
Average score 6.9/10 across 96 analyzed source files; 34 hotspots surfaced.
packages/lit-query/src/__tests__/createQueriesController.test-d.ts— 1310 lines, score 4 (Large file, Deep nesting)packages/react-query/src/__tests__/useQueries.test-d.tsx— 1040 lines, score 4 (Large file, Deep nesting)packages/solid-query/src/__tests__/useQueries.test-d.tsx— 894 lines, score 4.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
29859ae60c8d2026-10-02 — ci: Version Packages (#11806)ec060b6f74b22026-10-02 — fix(query-devtools): isolate signals on devtools instances (#11799)94e20031dd0a2026-10-02 — test(lit-query/createQueryController): add test for removing the observer from the query when destroyed (#11804)d49c1f5885912026-10-02 — test(lit-query/useMutationState): add test for returning the current mutation states when connected after a mutation started (#11803)d547e2195dfd2026-10-02 — test(lit-query/createQueriesController): add test for not having stale closures with 'combine' (#11802)