Registry / http-networking / react-query

react-query

library3.39.3jsnpmunverified

react-query is a robust and widely adopted library for managing, caching, and synchronizing asynchronous data within React applications. This registry entry refers to version 3.x.x of the `react-query` package, with 3.39.3 being the latest patch provided. Since late 2021, active development and new major versions (v4, v5) have transitioned to the `@tanstack/react-query` package as part of a broader monorepo rebrand. Consequently, the `react-query` package (v3) is now in a maintenance-only phase, receiving critical bug fixes but no new features. Its key differentiators include declarative data fetching via hooks (`useQuery`, `useMutation`), automatic background refetching, efficient data caching with configurable stale-time and cache-time, optimistic updates, and a powerful devtools extension. It significantly reduces boilerplate for data management compared to traditional state management solutions for remote data.

http-networking web-framework

npm install react-query

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-QUERY

react-query

http-networkingjavascriptv3.39.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useQuery

✓ import { useQuery } from 'react-query'

✗ import { useQuery } from '@tanstack/react-query'

For v3, import from 'react-query'. For v4+, use '@tanstack/react-query'.

useMutation

✓ import { useMutation } from 'react-query'

✗ const useMutation = require('react-query').useMutation

Primarily used as an ES Module in modern React projects. CommonJS require is generally avoided.

QueryClient

✓ import { QueryClient } from 'react-query'

✗ import QueryClient from 'react-query'

QueryClient is a named export, not a default export.

QueryClientProvider

✓ import { QueryClientProvider } from 'react-query'

Needed to provide the QueryClient instance to the React component tree.

This quickstart demonstrates setting up QueryClientProvider and fetching data with useQuery to display a list of todos. It includes basic loading and error states.

import React from 'react'; import { QueryClient, QueryClientProvider, useQuery } from 'react-query'; // Create a client const queryClient = new QueryClient(); function Todos() { const { isLoading, error, data } = useQuery('todos', async () => { const response = await fetch('https://jsonplaceholder.typicode.com/todos'); if (!response.ok) { throw new Error('Network response was not ok'); } return response.json(); }); if (isLoading) return <p>Loading todos...</p>; if (error) return <p>An error occurred: {error.message}</p>; return ( <div> <h1>Todos</h1> <ul> {data.slice(0, 10).map((todo) => ( <li key={todo.id}>{todo.title}</li> ))} </ul> </div> ); } export default function App() { return ( <QueryClientProvider client={queryClient}> <Todos /> </QueryClientProvider> ); }

Debug

Known issues

breakingThe `react-query` package is superseded by `@tanstack/react-query` for v4 and beyond. Continuing to use `react-query` (v3) means you will not receive new features or active development, only critical bug fixes.

fix

Migrate your application to `@tanstack/react-query` by updating package names and reviewing breaking changes in the TanStack Query migration guides (e.g., `isLoading` vs `isInitialLoading`, query function return types). A codemod is available for some migrations.

affects: >=3.x

breakingIn `react-query` v3, `QueryCache` was split into `QueryClient`, `QueryCache`, and `MutationCache`. Direct interaction with `QueryCache` and `MutationCache` is less common, with `QueryClient` serving as the primary interface for configuration and interaction.

fix

Ensure you are instantiating and providing a `QueryClient` via `QueryClientProvider` at the root of your application. Directly manipulating `QueryCache` may require changes to use `QueryClient` methods.

affects: >=3.0

gotchaQuery functions must return a Promise that either resolves with data or *throws* an error for React Query to correctly handle error states. Libraries like `fetch` do not throw on HTTP error codes by default.

fix

Wrap `fetch` calls with logic to `throw new Error()` if `response.ok` is false. For Axios, errors are typically thrown automatically.

affects: >=3.x

gotchaWhen migrating from `react-query` v3 to `@tanstack/react-query` v4, note that `isLoading` for disabled queries behaves differently and might need to be replaced with `isInitialLoading` in specific scenarios. Also, query functions cannot return `undefined` for successful queries in v4.

fix

Review `useQuery` calls, especially with the `enabled` option, and update `isLoading` checks to `isInitialLoading` if the query is disabled. Change query functions returning `undefined` to return `null` or throw an error.

affects: >=3.x

Errors

Common errors & fixes

No QueryClient set, use QueryClientProvider to set one

The `useQuery` or `useMutation` hook was called in a component that is not a descendant of `QueryClientProvider`.

fix

Wrap your application or the relevant component tree with `QueryClientProvider`, passing an instance of `QueryClient` as the `client` prop. Place it high in the component hierarchy, typically in `App.js` or `index.js`.

React Hook "useQuery" cannot be called inside a callback. React Hooks must be called in a React function component or a custom React Hook function.

Attempting to call `useQuery` (or any React Hook) outside of a functional React component's top level or a custom hook function.

fix

Ensure `useQuery` is called directly within a React functional component or a custom hook that itself adheres to the rules of hooks.

Property 'message' does not exist on type 'unknown'.

TypeScript's default error type in catch blocks is `unknown` (since TS 4.4), and React Query's `error` state is typed as `unknown` by default, requiring type narrowing to access properties like `message`.

fix

Narrow the type of the `error` object before accessing its properties, typically using `if (error instanceof Error)` or a type guard for specific error types like `AxiosError`.

Upgrade

Version history

3.39.3latest on npm

Audit

Dependencies

reactrequiredRequired peer dependency for React component integration.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/tannerlinsley/react-query ↗

packagehttps://www.npmjs.com/package/react-query ↗

homepagehttps://tanstack.com/query ↗