Вступление
Разработчики React-приложений постоянно пишут однотипный код для работы с данными: useEffect, useState, reducers. Каждый новый экран — дублирование логики загрузки, кэширования и обновления. В результате 60–70% кода — бойлерплейт, который отвлекает от бизнес-логики. На одном проекте мы заменили Redux Thunk на TanStack Query и сократили код на 70%, а число багов упало в 3 раза.
TanStack Query (ранее React Query) — библиотека для управления серверным состоянием. Она берёт на себя кэширование, фоновые обновления, дедупликацию запросов, пагинацию, мутации с оптимистичными обновлениями и prefetching. Результат: объём кода для работы с данными сокращается на 60–70%, а количество багов уменьшается в 2–3 раза. Мы настраиваем TanStack Query с 2020 года, выполнили более 50 проектов. Гарантируем стабильную работу и экономию времени на 30–50%. Закажите настройку — получите готовую архитектуру данных за считанные дни.
| Подход | Бойлерплейт | Сложность | Масштабируемость |
|---|---|---|---|
| Redux Thunk | Высокий | Высокая | Средняя |
| RTK Query | Средний | Средняя | Высокая |
| TanStack Query | Низкий | Низкая | Высокая |
| SWR | Низкий | Низкая | Средняя |
Какие проблемы решает TanStack Query?
Проблема ручного управления кэшем: без библиотеки приходится вручную синхронизировать запросы, обрабатывать загрузку и ошибки. TanStack Query автоматически кэширует данные, дедуплицирует параллельные запросы и обновляет кэш при мутациях. Ещё одна боль — инвалидация кэша. С иерархическими ключами вы можете одной командой сбросить все связанные списки, не затрагивая детали.
Как настроить QueryClient с оптимальными параметрами?
QueryClient — центральный объект, управляющий всеми запросами. Его настройка влияет на производительность. Вот рекомендуемые значения:
| Параметр | По умолчанию | Рекомендуется | Зачем |
|---|---|---|---|
staleTime |
0 | 5 * 60 * 1000 | Данные считаются свежими 5 минут, не делается повторный запрос при каждом монтировании |
gcTime |
5 * 60 * 1000 | 10 * 60 * 1000 | Кэш хранится 10 минут после удаления ссылок (бывший cacheTime) |
retry |
3 | 2 | Попытки при ошибке — достаточно для временных сбоев |
refetchOnWindowFocus |
false | true | Автоматически обновлять данные при возвращении на вкладку |
Пример базовой инициализации:
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 5 * 60 * 1000,
gcTime: 10 * 60 * 1000,
retry: 2,
refetchOnWindowFocus: true,
},
mutations: {
retry: 0,
},
},
})
function App() {
return (
<QueryClientProvider client={queryClient}>
<Router />
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
)
}
Если проект использует Next.js App Router, мы добавляем серверный prefetch через dehydrate и HydrationBoundary.
Почему query keys — ключ к эффективной инвалидации?
Query keys — уникальные идентификаторы запроса. Правильная структура ключей определяет, как кэш инвалидируется после мутаций. Мы используем иерархический подход:
export const queryKeys = {
products: {
all: ['products'] as const,
lists: () => [...queryKeys.products.all, 'list'] as const,
list: (filters: ProductFilters) => [...queryKeys.products.lists(), filters] as const,
details: () => [...queryKeys.products.all, 'detail'] as const,
detail: (id: string) => [...queryKeys.products.details(), id] as const,
},
users: {
all: ['users'] as const,
me: () => [...queryKeys.users.all, 'me'] as const,
profile: (id: string) => [...queryKeys.users.all, 'profile', id] as const,
},
}
Благодаря этому можно инвалидировать все списки продуктов одной командой, не затрагивая детали.
Основные хуки: useQuery, useMutation, useInfiniteQuery
Базовый хук для получения данных — useQuery. Он возвращает состояние загрузки, ошибки и данные. Для критичного UI используйте useSuspenseQuery с React Suspense.
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
export function useProducts(filters: ProductFilters) {
return useQuery({
queryKey: queryKeys.products.list(filters),
queryFn: () => api.get<Product[]>('/products', { params: filters }),
placeholderData: (prev) => prev,
})
}
export function useUpdateProduct() {
const queryClient = useQueryClient()
return useMutation({
mutationFn: ({ id, data }: { id: string; data: UpdateProductDto }) =>
api.patch<Product>(`/products/${id}`, data),
onMutate: async ({ id, data }) => {
await queryClient.cancelQueries({ queryKey: queryKeys.products.detail(id) })
const previous = queryClient.getQueryData<Product>(queryKeys.products.detail(id))
queryClient.setQueryData(queryKeys.products.detail(id), (old: Product) => ({ ...old, ...data }))
return { previous }
},
onError: (_, { id }, context) => {
if (context?.previous) {
queryClient.setQueryData(queryKeys.products.detail(id), context.previous)
}
},
onSettled: (_, __, { id }) => {
queryClient.invalidateQueries({ queryKey: queryKeys.products.detail(id) })
},
})
}
Для бесконечной прокрутки — useInfiniteQuery:
export function useInfiniteProducts(filters: Omit<ProductFilters, 'page'>) {
return useInfiniteQuery({
queryKey: queryKeys.products.list(filters),
queryFn: ({ pageParam }) =>
api.get<PaginatedResponse<Product>>('/products', { params: { ...filters, page: pageParam, pageSize: 20 } }),
initialPageParam: 1,
getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
})
}
Для простой пагинации используйте keepPreviousData в placeholderData.
Как реализовать оптимистичные обновления без боли?
Оптимистичное обновление — интерфейс меняется до ответа сервера. TanStack Query делает это просто: в onMutate обновляем кэш, в onError откатываем. Пример выше с useUpdateProduct показывает эту технику. Пользователь видит мгновенную обратную связь, а при ошибке данные возвращаются к исходному состоянию.
Prefetching и SSR с Next.js
Prefetching загружает данные до перехода на страницу. Например, при наведении на ссылку:
function ProductLink({ id }: { id: string }) {
const queryClient = useQueryClient()
return (
<Link to={`/products/${id}`}
onMouseEnter={() => {
queryClient.prefetchQuery({
queryKey: queryKeys.products.detail(id),
queryFn: () => api.get<Product>(`/products/${id}`),
staleTime: 60_000,
})
}}
>Перейти</Link>
)
}
Для SSR в Next.js App Router используем серверный prefetchQuery и HydrationBoundary:
import { HydrationBoundary, QueryClient, dehydrate } from '@tanstack/react-query'
export default async function ProductsPage() {
const queryClient = new QueryClient()
await queryClient.prefetchQuery({
queryKey: queryKeys.products.lists(),
queryFn: () => fetchProductsServer(),
})
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<ProductList />
</HydrationBoundary>
)
}
Подробнее — в официальной документации TanStack Query.
Что входит в нашу услугу
Мы настраиваем TanStack Query под ваш проект:
- Установка и конфигурация QueryClient с учётом особенностей вашего API.
- Проектирование иерархии query keys для удобной инвалидации.
- Написание кастомных хуков для всех endpoints: useQuery, useMutation, useInfiniteQuery.
- Реализация оптимистичных обновлений для форм (лайки, комментарии, редактирование).
- Настройка prefetching и интеграция с SSR/Next.js.
- Подключение DevTools для отладки.
- Документация и обучение команды.
Процесс работы:
- Аналитика — аудит текущего стека и API, определение точек интеграции.
- Проектирование — схемы query keys, выбор стратегии кэширования.
- Реализация — написание хуков, тестирование мутаций, оптимизация.
- Тестирование — проверка инвалидации, авторизации, edge-кейсов.
- Деплой — развёртывание, мониторинг через DevTools.
Сроки: от 2 до 5 дней в зависимости от количества Endpoints. Стоимость рассчитывается индивидуально. Экономия на дальнейшей поддержке окупает затраты в течение нескольких недель.
Свяжитесь с нами для консультации — мы поможем внедрить TanStack Query и сократить время разработки на 30–50%. Получите готовую архитектуру данных за считанные дни.