TanStack Query is a framework-agnostic async state management library designed to simplify fetching, caching, synchronizing, and updating server state in web applications. This document provides a high-level overview of the monorepo structure, package ecosystem, and core architecture. For detailed information about specific components, see Core Architecture, Framework Integrations, and Examples.
TanStack Query solves the problem of managing server state—data that exists remotely and must be fetched asynchronously. Unlike client state, server state is asynchronous, can become stale, may need background updates, and requires caching strategies. The library provides:
Sources: README.md37-42
The TanStack Query repository is organized as a pnpm workspace monorepo with three primary directory structures:
Directory Structure:
| Directory | Purpose | Entry Point |
|---|---|---|
packages/ | Publishable npm packages | Individual package.json files |
examples/ | Framework-specific demos | Per-example package.json |
scripts/ | Build tooling | generate-docs.ts, verify-links.ts |
.github/workflows/ | CI/CD pipelines | pr.yml, release.yml, ci.yml |
The monorepo uses workspace protocols (workspace:*) to link packages during development, allowing examples to depend on local package versions.
Sources: README.md1-106 package.json1-96
TanStack Query follows a layered architecture where a framework-agnostic core provides all data management logic, and framework-specific adapters wrap this core with idiomatic APIs.
@tanstack/query-core is the foundation package containing all framework-agnostic logic:
Sources: packages/query-core/package.json1-65
Each framework adapter package provides framework-specific APIs that wrap the core:
| Package | Primary Exports | Reactive Primitive | Versions |
|---|---|---|---|
@tanstack/react-query | useQuery, useInfiniteQuery, useMutation, useQueryClient | React hooks | React 18-19 |
@tanstack/vue-query | useQuery, useInfiniteQuery, useMutation | Vue composables | Vue 2.6-3.x |
@tanstack/solid-query | createQuery, createInfiniteQuery, createMutation | Solid primitives | Solid 1.6+ |
@tanstack/svelte-query | createQuery, createInfiniteQuery, createMutation | Svelte stores | Svelte 5.25+ |
@tanstack/angular-query-experimental | injectQuery, injectInfiniteQuery, injectMutation | Angular signals | Angular signals |
Sources: packages/react-query/package.json1-87 packages/vue-query/package.json1-87 packages/solid-query/package.json1-82 packages/svelte-query/package.json1-67
The devtools system follows the same layered pattern:
Each framework-specific devtools package declares its corresponding query package as a peer dependency, ensuring version compatibility.
Sources: packages/react-query-devtools/package.json81-95
The persistence layer enables saving and restoring query cache state:
Sources: packages/query-persist-client-core/package.json1-68 packages/query-async-storage-persister/package.json1-69 packages/query-sync-storage-persister/package.json1-69 packages/react-query-persist-client/package.json1-77
| Package | Purpose |
|---|---|
@tanstack/eslint-plugin-query | ESLint rules for query best practices |
@tanstack/react-query-next-experimental | Next.js App Router integration utilities |
@tanstack/query-broadcast-client-experimental | Cross-tab state synchronization via BroadcastChannel |
Sources: packages/query-broadcast-client-experimental/package.json1-69
The following diagram maps natural language concepts to concrete code entities in the core package:
Key Data Flow:
useQuery)QueryObserver instanceQuery from QueryCachequeryFn via RetryerSources: packages/query-core/package.json1-65 packages/react-query/package.json1-87
TanStack Query uses Nx as its build orchestration system:
Key Commands:
| Script | Command | Purpose |
|---|---|---|
test:pr | nx affected --targets=test:sherif,test:knip,test:docs,test:eslint,test:lib,test:types,test:build,build | Run all checks on affected packages |
test:ci | nx run-many --targets=... | Run full test suite |
build | nx affected --target=build --exclude=examples/** | Build affected packages |
test:types | Multiple TS versions via typescript50 through typescript57 | Validate against 9 TypeScript versions |
Testing Strategy:
publint and @arethetypeswrong/cliscripts/verify-links.tsSources: package.json10-41 packages/react-query-devtools/package.json17-36
The repository uses Changesets for version management:
The release process automatically publishes packages to npm with provenance attestation when the "Version Packages" PR is merged. Each package maintains independent semantic versioning.
Sources: package.json30-32
All packages use dual-format exports supporting both ESM and CommonJS:
Export Configuration Pattern:
The @tanstack/custom-condition export allows internal monorepo packages to reference source TypeScript directly during development, bypassing the build step.
Sources: packages/query-core/package.json36-54 packages/react-query/package.json38-56
For local development setup and contribution guidelines, see Contributing. For understanding how the core architecture works, see Core Architecture. For framework-specific integration details, see Framework Integrations.
Refresh this wiki