Что такое TanStack Query (React Query) и зачем использовать?

TanStack Query (React Query)

TanStack Query (ранее React Query) — это библиотека для работы с серверным состоянием (server state) в React. Она решает задачи получения, кэширования, синхронизации и обновления данных с сервера.

Зачем нужна, если есть Redux / Zustand?

Global state-менеджеры отлично справляются с клиентским состоянием (UI-флаги, форма, выбранные фильтры), но серверное состояние имеет принципиально другую природу:

• Хранится удалённо и может устареть в любой момент
• Требует кэширования, дедупликации запросов и фоновой синхронизации
• Имеет состояния loading, error, stale, fetching

Писать всё это вручную через useEffect + useState — много повторяющегося кода с трудно предсказуемыми edge-кейсами.

Ключевые возможности

Кэширование и stale-while-revalidate — данные кэшируются по ключу, и при повторном запросе сразу возвращается кэш, пока в фоне идёт обновление.

Автоматическое обновление — при фокусировке вкладки, восстановлении сети или по интервалу данные обновляются автоматически.

Дедупликация запросов — несколько компонентов с одним ключом запроса не создают несколько HTTP-запросов.

Инвалидация кэша — после мутации (создание, обновление, удаление) можно точечно инвалидировать нужные запросы.

Пагинация и бесконечный скролл — встроенные хуки useInfiniteQuery.

Базовый пример

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

// Получение списка пользователей
function UserList() {
  const { data, isLoading, isError } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(res => res.json()),
    staleTime: 1000 * 60, // данные считаются свежими 1 минуту
  })

  if (isLoading) return <div>Загрузка...</div>
  if (isError) return <div>Ошибка загрузки</div>

  return <ul>{data.map(u => <li key={u.id}>{u.name}</li>)}</ul>
}

Мутации с инвалидацией

function CreateUser() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: (newUser) =>
      fetch('/api/users', {
        method: 'POST',
        body: JSON.stringify(newUser),
      }).then(res => res.json()),
    onSuccess: () => {
      // После создания инвалидируем кэш списка пользователей
      queryClient.invalidateQueries({ queryKey: ['users'] })
    },
  })

  return (
    <button
      onClick={() => mutation.mutate({ name: 'Иван' })}
      disabled={mutation.isPending}
    >
      {mutation.isPending ? 'Создание...' : 'Создать пользователя'}
    </button>
  )
}

Настройка провайдера

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

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 30,  // 30 секунд по умолчанию
      retry: 2,              // повторить запрос 2 раза при ошибке
    },
  },
})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <UserList />
    </QueryClientProvider>
  )
}

Когда не нужен TanStack Query

• Данные загружаются один раз при старте и не меняются (конфиги, константы)
• SSR-приложение с серверными компонентами (Next.js App Router) — там предпочтительнее fetch на сервере
• Очень простое приложение с 1–2 запросами без кэширования