1. Установка и настройка

Что ставить

npm install @tanstack/react-query
npm install -D @tanstack/react-query-devtools

Опциональные пакеты:

• @tanstack/react-query-devtools для инспектора кеша.
• @tanstack/react-query-persist-client для персистентности.
• @tanstack/query-sync-storage-persister или @tanstack/query-async-storage-persister для storage-persister.
• @tanstack/query-broadcast-client-experimental только если вам нужна синхронизация между вкладками и вы принимаете experimental-статус.

Минимальная настройка

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,
      gcTime: 5 * 60_000,
      retry: 3,
    },
  },
})

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

Главная идея: в браузере у вас почти всегда должен жить один стабильный QueryClient, а не новый экземпляр на каждый рендер.

Важные значения по умолчанию

• Все запросы по умолчанию считаются stale.
• stale-запросы автоматически рефетчатся при маунте, возврате фокуса окна и восстановлении сети.
• Ошибочные запросы по умолчанию ретраятся 3 раза с backoff.
• Неактивные запросы по умолчанию удаляются из кеша через 5 минут (gcTime).
• Структурное сравнение (structuralSharing) включено по умолчанию.

Рекомендуемый QueryClient

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

export function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60_000,
        gcTime: 10 * 60_000,
        retry: (failureCount, error) => {
          if (error instanceof Response && error.status < 500) return false
          return failureCount < 3
        },
      },
      mutations: {
        retry: 0,
      },
    },
  })
}

Практика:

• staleTime > 0 почти всегда улучшает UX.
• Не ставьте gcTime: Infinity без причины.
• Для мутаций чаще всего retry: 0 или кастомная стратегия понятнее, чем слепой повтор.

Безопасный провайдер для SSR и App Router

Официальный паттерн для React 18+/Next.js App Router: новый клиент на сервере, singleton в браузере.

'use client'

import {
  isServer,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60_000,
      },
    },
  })
}

let browserQueryClient: QueryClient | undefined

function getQueryClient() {
  if (isServer) return makeQueryClient()
  if (!browserQueryClient) browserQueryClient = makeQueryClient()
  return browserQueryClient
}

export function Providers({ children }: { children: React.ReactNode }) {
  const queryClient = getQueryClient()

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

Почему так:

• На сервере нельзя шарить один QueryClient между запросами разных пользователей.
• В браузере нельзя создавать новый клиент на каждый рендер.
• В App Router важно не терять клиент, если верхняя часть дерева может суспендиться при первом рендере.

Devtools

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

<QueryClientProvider client={queryClient}>
  <App />
  {import.meta.env.DEV ? <ReactQueryDevtools initialIsOpen={false} /> : null}
</QueryClientProvider>

Настройка под разные типы данных

• Справочники и feature flags: staleTime: Infinity.
• Данные дашборда: staleTime от 15s до 60s.
• Профиль пользователя: часто 1-5 минут.
• Живые списки: короткий staleTime или ручная инвалидация по событию.
• Полностью ручной контроль: staleTime: 'static', если вы не хотите автоматический рефетч даже после инвалидции.

Чего избегать

• new QueryClient() прямо внутри компонента без стабилизации.
• Глобальных refetchOnWindowFocus: false без понимания, зачем вы отключаете поведение по умолчанию.
• Смешивания server state и client state в одном сторе “на всякий случай”.

Чек-лист

• Один стабильный QueryClient в браузере.
• Новый QueryClient на каждый SSR-запрос.
• Подключены Devtools в development.
• Заданы осмысленные staleTime и gcTime.
• Команда понимает, что stale не означает “сломанный”, а означает “может требовать фонового обновления”.