Концепция серверного состояния

TanStack Query ориентирован на современный JavaScript и активно использует возможности стандарта ES2015+:

  • Promise
  • async/await
  • стрелочные функции
  • деструктуризацию
  • Map
  • Set
  • модульную систему ES Modules

Минимальные требования зависят от используемого окружения и сборщика, однако на практике чаще всего применяются:

  • Node.js 18+
  • современные версии Chrome, Firefox, Edge и Safari
  • ECMAScript 2020+

При использовании старых браузеров требуется подключение полифиллов:

import 'core-js/stable';
import 'regenerator-runtime/runtime';

Без поддержки Promise библиотека работать не сможет, поскольку вся её архитектура построена вокруг асинхронных запросов.

Требования к Node.js

Для современных версий TanStack Query рекомендуется использовать актуальные LTS-версии Node.js.

Наиболее распространённые варианты:

Версия Node.js Статус
18.x Рекомендуется
20.x Полная поддержка
22.x Поддерживается

Проверка установленной версии:

node -v

Проверка npm:

npm -v

Проверка pnpm:

pnpm -v

Проверка yarn:

yarn -v

Поддерживаемые пакетные менеджеры

TanStack Query не зависит от конкретного пакетного менеджера и корректно работает с:

  • npm
  • yarn
  • pnpm
  • bun

Примеры установки:

npm

npm install @tanstack/react-query

yarn

yarn add @tanstack/react-query

pnpm

pnpm add @tanstack/react-query

bun

bun add @tanstack/react-query

Поддерживаемые фреймворки

TanStack Query является частью экосистемы TanStack и поддерживает несколько UI-фреймворков.

React

Наиболее популярный вариант:

npm install @tanstack/react-query

Vue

npm install @tanstack/vue-query

Solid

npm install @tanstack/solid-query

Svelte

npm install @tanstack/svelte-query

Angular

Для Angular существуют адаптеры и интеграции сообщества.

Требования к React

Для React-проекта чаще всего используются:

Библиотека Рекомендуемая версия
React 18+
React DOM 18+

Проверка версии:

npm list react

или:

yarn why react

TanStack Query активно использует возможности современных React API:

  • Concurrent Rendering
  • Suspense
  • Error Boundaries
  • Hooks API

Старые версии React могут работать нестабильно или требовать дополнительных настроек.

Поддержка TypeScript

Хотя библиотека полностью работоспособна на обычном JavaScript, её архитектура изначально создавалась с учётом TypeScript.

Рекомендуемые версии:

Инструмент Версия
TypeScript 5+

Установка:

npm install typescript --save-dev

TanStack Query предоставляет:

  • мощную систему дженериков
  • автоматический вывод типов
  • типизацию ответов API
  • типизацию ошибок
  • типизацию ключей запросов

Пример конфигурации TypeScript:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "moduleResolution": "Node",
    "jsx": "react-jsx"
  }
}

Требования к сборщикам

TanStack Query совместим практически со всеми современными сборщиками.

Vite

Наиболее рекомендуемый вариант.

Преимущества:

  • быстрый HMR
  • нативные ES-модули
  • минимальная конфигурация
  • высокая скорость запуска

Создание проекта:

npm create vite@latest

Webpack

Полностью поддерживается:

npm install webpack webpack-cli webpack-dev-server

Для старых конфигураций Webpack может потребоваться:

  • Babel
  • настройка tree-shaking
  • поддержка ESM

Parcel

Работает без дополнительной настройки:

npm install parcel

Rollup

Часто используется для библиотек:

npm install rollup

Next.js

TanStack Query отлично интегрируется с:

  • SSR
  • SSG
  • ISR
  • React Server Components

Установка:

npm install next react react-dom

Дополнительно часто используется:

npm install @tanstack/react-query-devtools

Требования к браузерам

Минимальные требования определяются поддержкой современных API.

Полностью поддерживаются

Браузер Версия
Chrome последние версии
Firefox последние версии
Edge последние версии
Safari последние версии

Ограниченная поддержка

Браузер Особенности
Internet Explorer не поддерживается
Старые Android WebView требуются полифиллы

Требования к сетевому слою

TanStack Query не выполняет HTTP-запросы самостоятельно. Библиотека лишь управляет состоянием запросов.

Поэтому требуется отдельный HTTP-клиент.

Наиболее распространённые варианты:

Fetch API

const response = await fetch('/api/users');
const data = await response.json();

Axios

npm install axios

Пример:

import axios from 'axios';

const { data } = await axios.get('/api/users');

GraphQL-клиенты

Поддерживаются:

  • graphql-request
  • Apollo Client
  • urql

Требования к React Hooks

TanStack Query строится вокруг React Hooks.

Необходимо соблюдение правил хуков:

  • вызов только на верхнем уровне компонента
  • запрет вызова внутри условий
  • запрет вызова внутри циклов
  • запрет вызова внутри вложенных функций

Неправильно:

if (isAdmin) {
  useQuery(...);
}

Правильно:

const query = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  enabled: isAdmin
});

Требования к структуре проекта

Типичная структура проекта:

src/
├── api/
├── hooks/
├── queries/
├── mutations/
├── services/
├── pages/
├── components/
└── providers/

Часто отдельно выносятся:

  • query keys
  • query functions
  • API-клиенты
  • конфигурации QueryClient
  • глобальные обработчики ошибок

Требования к QueryClient

TanStack Query требует обязательного создания экземпляра QueryClient.

Минимальная конфигурация:

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

export const queryClient = new QueryClient();

Без него библиотека функционировать не сможет.

Требования к QueryClientProvider

Все React-компоненты, использующие TanStack Query, должны находиться внутри QueryClientProvider.

Пример:

import React from 'react';
import ReactDOM from 'react-dom/client';

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

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById('root')).render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
);

Требования к Devtools

Для разработки рекомендуется подключение Devtools.

Установка:

npm install @tanstack/react-query-devtools

Подключение:

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

<ReactQueryDevtools initialIsOpen={false} />

Devtools позволяют:

  • просматривать кэш
  • отслеживать запросы
  • анализировать stale/fresh состояния
  • контролировать retry
  • отслеживать invalidateQueries

Требования к серверному рендерингу

При SSR требуется:

  • отдельный QueryClient на каждый запрос
  • гидратация состояния
  • сериализация кэша
  • предотвращение утечек памяти

Для Next.js используется:

npm install @tanstack/react-query

и API:

dehydrate()
hydrate()
HydrationBoundary

Требования к ESLint

Для предотвращения ошибок рекомендуется использование:

npm install eslint eslint-plugin-react-hooks

Основные правила:

  • react-hooks/rules-of-hooks
  • react-hooks/exhaustive-deps

Они помогают избежать:

  • неправильного вызова хуков
  • бесконечных ререндеров
  • потери зависимостей

Требования к производительности

TanStack Query активно использует:

  • кэширование
  • дедупликацию запросов
  • фоновые обновления
  • garbage collection
  • структурное сравнение данных

Для корректной работы рекомендуется:

  • стабильные query keys
  • мемоизация параметров
  • отказ от создания новых объектов на каждом рендере

Плохо:

useQuery({
  queryKey: [{ page: 1 }]
});

Лучше:

useQuery({
  queryKey: ['users', 1]
});

Требования к архитектуре API

Наиболее эффективно TanStack Query работает при:

  • REST API
  • GraphQL API
  • JSON-ответах
  • предсказуемых структурах данных
  • стабильных идентификаторах сущностей

Желательно наличие:

  • HTTP-кодов ошибок
  • пагинации
  • фильтрации
  • сортировки
  • cursor-based pagination

Требования к асинхронным функциям

Все query functions должны возвращать Promise.

Правильно:

const fetchUsers = async () => {
  const response = await fetch('/api/users');

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
};

Неправильно:

const fetchUsers = () => {
  fetch('/api/users');
};

Требования к обработке ошибок

Функции запросов должны выбрасывать ошибки, а не скрывать их.

Неправильно:

const fetchUsers = async () => {
  try {
    const response = await fetch('/api/users');
    return await response.json();
  } catch {
    return [];
  }
};

Правильно:

const fetchUsers = async () => {
  const response = await fetch('/api/users');

  if (!response.ok) {
    throw new Error('Failed request');
  }

  return response.json();
};

Требования к стабильности queryKey

Ключи запросов должны быть:

  • сериализуемыми
  • предсказуемыми
  • стабильными

Рекомендуется использовать массивы:

['users']
['users', userId]
['users', userId, filters]

Нежелательно использовать:

  • функции
  • классы
  • DOM-элементы
  • случайные значения

Требования к памяти

TanStack Query хранит данные в памяти приложения.

При больших объёмах данных важно учитывать:

  • cacheTime
  • gcTime
  • размер кэша
  • количество активных запросов

Пример:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 1000 * 60 * 10
    }
  }
});

Требования к безопасности

TanStack Query не выполняет автоматическую защиту данных.

Безопасность должна обеспечиваться отдельно:

  • HTTPS
  • CSRF-защита
  • авторизация
  • refresh token
  • secure cookies
  • проверка JWT
  • защита API

Библиотека лишь управляет состоянием клиентских запросов и не заменяет backend-механизмы безопасности.

Оглавление