React Query v3 (Legacy)

Common errors

• No QueryClient set, use QueryClientProvider to set one

  cause 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.

  cause 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'.

  cause 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`.

Warnings

• breaking The `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.
• breaking In `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.
• gotcha Query 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.
• gotcha When 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.

Install

• npm install react-query npm
• yarn add react-query yarn
• pnpm add react-query pnpm

Imports

• useQuery
  wrong:

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

  correct:

  import { useQuery } from 'react-query'

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

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

  correct:

  import { useMutation } from 'react-query'

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

  import QueryClient from 'react-query'

  correct:

  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.

Quickstart

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>
  );
}