TanStack Query для React

Актуальный учебник по TanStack Query для React, выровненный под официальную документацию latest на 2026 год. На практике это современная линия v5 со всеми актуальными стабильными API и отдельными пометками для experimental-возможностей.

Для кого этот учебник

• Для тех, кто хочет понять не только useQuery, но и весь жизненный цикл server state.
• Для тех, кто использует React 18+, Next.js App Router, Suspense, SSR или offline-first сценарии.
• Для команд, которым нужен не набор заметок, а целостная карта тем: от первого запроса до production-практик.

Как читать

1. Сначала пройдите главы 1-4, чтобы собрать базовую модель.
2. Затем главы 5-10, чтобы освоить реальные паттерны приложения.
3. После этого переходите к 11-15, если у вас есть SSR, офлайн, производительность, тесты или realtime.

Содержание

1. Установка и настройка
2. Запросы и Query Options
3. Query Keys и кеш
4. Query Functions и работа с API
5. Параллельные и зависимые запросы
6. Мутации и оптимистичные апдейты
7. Инвалидация и фоновые обновления
8. Пагинация и Infinite Query
9. Prefetch, Hydration и начальные данные
10. Suspense и Error Boundaries
11. Devtools и диагностика производительности
12. Персистентность, офлайн и SSR
13. Рендер-оптимизации и Request Waterfalls
14. Тестирование и качество
15. Realtime, мультивкладочность и experimental API

Что обновлено относительно старых конспектов

• Текст приведён к актуальным latest API: queryOptions, infiniteQueryOptions, HydrationBoundary, usePrefetchQuery, usePrefetchInfiniteQuery, useSuspenseQueries, skipToken.
• Убраны неточные или спорные советы, которые больше не совпадают с официальной документацией.
• Добавлены полноценные главы про request waterfalls, render optimizations, тестирование, multi-tab sync и experimental streaming.
• Все примеры выстроены вокруг рекомендуемого подхода: фабрики опций, стабильные queryKey, иммутабельные обновления кеша, предзагрузка и SSR через один и тот же набор query options.

Короткая карта понятий

• queryKey отвечает за идентичность данных.
• queryFn знает, как данные получить.
• QueryClient управляет кешем, инвалидацией, префетчем, гидратацией и мутациями.
• staleTime отвечает за свежесть.
• gcTime отвечает за удаление неактивных данных из кеша.
• invalidateQueries помечает данные устаревшими.
• setQueryData меняет кеш вручную без сетевого запроса.
• prefetchQuery и ensureQueryData помогают убрать client-side waterfall.

Практический совет

Если в проекте начинают множиться одинаковые queryKey, ручные refetch() и useEffect вокруг запросов, значит пора вернуться к главам 3, 5, 7 и перестроить код в более декларативный стиль.

Официальная база

• React docs: https://tanstack.com/query/latest/docs/framework/react/
• QueryClient reference: https://tanstack.com/query/latest/docs/reference/QueryClient
• Advanced SSR: https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr
• Query cancellation: https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation