Installation

Purpose and Scope

This page explains how to add TanStack Query to a React application and how to choose the correct package for that application boundary. In the React docs, the install target is @tanstack/react-query, not a lower-level package, because React users consume Query through React-specific APIs such as providers, hooks, and React-compatible hydration or suspense integrations. The installation page also shows that the same package exports core concepts such as QueryClient, which is the object you create before wiring Query into an app. Sources: docs/framework/react/installation.md

TanStack Query is a server-state library: it helps fetch, cache, synchronize, and update asynchronous data that lives outside the client UI tree. Installation is therefore more than adding a dependency; it is the first decision about which framework adapter will own the application integration. For React, install the React adapter and let it bring the Query runtime surface you need. In multi-framework workspaces, use the adapter package that matches the rendering framework, while treating query concepts like clients, caches, keys, and observers as shared vocabulary across the ecosystem.

Relevant Source Files

docs/framework/react/installation.md - The first-party React installation page. It defines the supported install channels, package-manager commands, React compatibility statement, CDN import example, browser requirements, and ESLint plugin recommendation used by this guide.

NPM and Package Manager Installation

For modern React projects with a bundler or package manager, install the React adapter package directly. The official installation page gives equivalent commands for common JavaScript package managers, including npm, pnpm, yarn, bun, and deno. Pick the command that matches the package manager already used by the application, then continue with the quick-start setup that creates a QueryClient and places the provider near the root of the React tree. Sources: docs/framework/react/installation.md

npm i @tanstack/react-query

pnpm add @tanstack/react-query

yarn add @tanstack/react-query

bun add @tanstack/react-query

deno add @tanstack/react-query

The important package-selection rule is to install @tanstack/react-query for React applications instead of installing only a generic cache package. The React package is the framework adapter: it is the boundary that presents Query through React-friendly APIs and is the package named throughout the React installation page. Other TanStack Query adapters exist for other frameworks, but the install command for this page is intentionally React-specific. If you later move a shared data-fetching pattern to another framework, keep the query-key and query-function concepts, then switch to that framework's adapter package and provider model.

React Compatibility and Runtime Targets

React Query is documented as compatible with React v18+ and works with both ReactDOM and React Native. That compatibility statement matters when deciding whether an existing application can adopt the current React adapter without changing renderers. A browser React app using ReactDOM and a mobile app using React Native can both use the same @tanstack/react-query package, but their surrounding platform integrations can differ after installation, especially around focus and online status handling. Sources: docs/framework/react/installation.md

The browser support floor is also explicit in the installation page: Chrome >= 91, Firefox >= 90, Edge >= 91, Safari >= 15, iOS >= 15, and Opera >= 77. These targets reflect an optimized modern-browser distribution. If an application must support older browsers, plan for polyfills and for transpiling the library from node_modules as the docs warn. That requirement is a build-pipeline decision, not a Query API decision, so verify it in the application bundler and test matrix before assuming legacy-browser support.

Chrome >= 91
Firefox >= 90
Edge >= 91
Safari >= 15
iOS >= 15
Opera >= 77

CDN Installation

If the application is not using a bundler or package manager, the installation page also supports loading React Query from an ESM-compatible CDN such as ESM.sh. This path is useful for prototypes, minimal HTML examples, or environments where native ES modules are sufficient. The docs show a <script type="module"> block that imports React, ReactDOM, and QueryClient from @tanstack/react-query. The named QueryClient import is a useful signal: even in CDN usage, the app still starts from the same client concept used in package-managed React apps. Sources: docs/framework/react/installation.md

<script type="module">
  import React from 'https://esm.sh/react@18.2.0'
  import ReactDOM from 'https://esm.sh/react-dom@18.2.0'
  import { QueryClient } from 'https://esm.sh/@tanstack/react-query'
</script>

Use the CDN path only when it matches the deployment model. Most production React applications should prefer a package manager because it gives the bundler control over dependency graph analysis, build transforms, and framework integration. The CDN example is still valuable for understanding package boundaries: the app imports React from React's package, the renderer from ReactDOM, and Query's client from the React Query package. If you are writing without JSX, the installation page points readers to React's own non-JSX guidance rather than duplicating React rendering instructions.

Adapter and Core Dependency Model

Think of @tanstack/react-query as the React-facing entry point for TanStack Query. It is the package you install in React projects because it aligns the shared Query runtime concepts with React application structure. The installation guide does not ask React users to manually install a separate framework-neutral core package for normal usage; instead, it presents the React adapter as the dependency to add and uses that package for the QueryClient import in the CDN example. Sources: docs/framework/react/installation.md

This distinction helps avoid two common setup mistakes. First, do not install an adapter for a framework you are not rendering with; a React app should not begin with a Vue, Solid, Angular, Lit, Svelte, or Preact package. Second, do not start by depending on the framework-neutral pieces directly unless you are building an adapter, integration, or specialized library. Application code usually wants the framework package because it includes the integration conventions that make queries observable by the UI and connect cache updates to renders.

Recommended Tooling

After installing the runtime package, the React installation page recommends adding the TanStack ESLint Plugin Query as a development dependency. The plugin is not required to run queries, but it helps catch bugs and inconsistencies while code is being written. This is a good default for teams because Query code often centralizes cache keys, option objects, stale-time choices, and hook usage; lint feedback makes those patterns easier to maintain during review. Sources: docs/framework/react/installation.md

npm i -D @tanstack/eslint-plugin-query

pnpm add -D @tanstack/eslint-plugin-query

yarn add -D @tanstack/eslint-plugin-query

bun add -D @tanstack/eslint-plugin-query

Treat the ESLint plugin as part of the installation checklist for a real project, especially if multiple developers will create queries and mutations. Install the runtime dependency first, confirm the application can import from @tanstack/react-query, then add the lint plugin and configure it in the repository's ESLint setup. Once the package is installed, the next step is the quick-start flow: create a QueryClient, wrap the React tree in QueryClientProvider, and call useQuery from a component.

Ask a question...