11. Devtools и диагностика производительности

Devtools помогают быстро увидеть всё, что происходит в кеше: статусы запросов, очереди мутаций, пересоздания ключей и частоту пересчётов селекторов. В v5 панель вынесена в @tanstack/react-query-devtools, умеет работать как встроенный виджет или отдельная вкладка и поддерживает тёмную тему, собственные кнопки и динамический импорт.

Быстрый чеклист перед расследованием

• Включите Devtools только для import.meta.env.DEV, чтобы не утянуть пакет в прод.
• Откройте глобальный индикатор useIsFetching() / useIsMutating() и сравните с тем, что показывает панель.
• Включите переключатели Sort by status, Show query keys и Show stale — они сразу подсвечивают проблемные запросы.
• Запишите таймлайн действий пользователя и отметьте, на каком этапе дергается refetch.
• Если подозреваете select, откройте вкладку Observers и посмотрите, сколько компонентов завязано на этот запрос.

Подключение

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

<QueryClientProvider client={queryClient}>
  <App />
  {import.meta.env.DEV && (
    <ReactQueryDevtools
      initialIsOpen={window.location.hash === '#rq'}
      position="bottom"
      buttonPosition="bottom-right"
      panelProps={{ style: { maxHeight: '45vh', boxShadow: '0 -8px 32px rgba(0,0,0,.35)' } }}
      buttonProps={{ 'aria-label': 'Toggle React Query Devtools' }}
      closeButtonProps={{ style: { opacity: 0.6 } }}
    />
  )}
</QueryClientProvider>

• position принимает top / bottom, а buttonPosition — любую сторону экрана, что удобно при тестировании адаптивов.
• Хэш #rq позволяет автоматически открывать панель, не трогая код.
• При SSR можно завернуть импорт ReactQueryDevtools в if (typeof window !== 'undefined'), чтобы не ломать билды.

Динамический импорт

const Devtools = import.meta.env.DEV
  ? lazy(() => import('@tanstack/react-query-devtools').then(m => ({ default: m.ReactQueryDevtools })))
  : () => null;

Используйте для уменьшения основного бандла; Suspense здесь подходит, потому что Devtools не критичны.

Отдельная панель или вкладка

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

export function QueryInspector() {
  const queryClient = useQueryClient();
  return import.meta.env.DEV ? (
    <ReactQueryDevtoolsPanel
      queryClient={queryClient}
      style=
      onClose={() => console.log('Devtools hidden')}
    />
  ) : null;
}

Такой компонент можно встроить в сторибуки, дизайн-системы или вынести в отдельное окно Electron.

Что показывает Devtools

• Queries: фильтр по ключам, статусу, активным/неактивным, наличию ошибок и времени обновления (Last Updated).
• Observers: количество подписчиков и их опции (staleTime, gcTime, select). Удобно искать компоненты, не отписавшиеся при размонтировании.
• Actions: ручной refetch, invalidate, reset, remove, setData. Кнопки позволяют симулировать фоновые события без изменения кода.
• Mutations: очередь мутаций, повторные попытки, ошибки сериализированные. Можно очистить (clear) или принудительно прервать.
• Settings: быстрые переключатели Focus refetching, Reconnect refetching, Structural sharing.

Полезные настройки панели

• Переключите Devtools в темный режим document.body.dataset.theme = 'dark', чтобы проверить, не конфликтуют ли стили проекта.
• Если панель закрывается при хоткеях пользователя, пробросьте toggleButtonProps={{ onKeyDown: e => e.stopPropagation() }}.
• Для мобильных дебаг-сессий увеличьте panelProps={{ style: { fontSize: '14px', padding: '1rem' } }} и закрепите кнопку сверху.

Диагностика рефетчей

1. Включите showStale. Если запрос мгновенно становится stale, значит staleTime = 0 и каждый фокус окна будет вызывать refetch.
2. Если ключ выглядит как [object Object], значит передаётся немемуизированный объект. В Devtools это легко увидеть, включив Show query keys.
3. Нажмите на строку запроса, вкладка Observers покажет options. Ищите параметры по умолчанию, которые не переопределены (например, refetchOnWindowFocus: true).
4. Посмотрите вкладку Events — там фиксируются observerAdded, observerRemoved, queryUpdated, queryGC. Если observerAdded срабатывает чаще, чем ожидалось, значит компоненты пересоздаются.
5. Используйте queryClient.getQueryCache().find({ queryKey })?.observers.length в runtime-логах, чтобы сверять с Devtools.

Логи и события

const unsubscribe = queryClient.getQueryCache().subscribe(event => {
  if (event?.type === 'queryObserverResultUpdated' && event.query.state.fetchStatus === 'fetching') {
    performance.mark(`rq:${event.query.queryHash}:fetching`);
  }
  if (event?.type === 'queryRemoved') {
    console.debug('[RQ] GC', event.query.queryKey);
  }
});

queryClient.getMutationCache().subscribe(event => {
  if (event?.type === 'mutationAdded') {
    console.info('[RQ] Mutation enqueued', event.mutation.options.mutationKey);
  }
});

• Можно подключить внешние логгеры (Datadog, Sentry breadcrumbs) и связывать их с действиями пользователя.
• Не забывайте unsubscribe() при размонтировании инструментов (например, в отдельном хелпере useReactQueryLogger()).

Профилирование ререндеров

• Сравните число пересчётов компонента (React DevTools Profiler) с количеством observer-апдейтов в Devtools. Если React показывает больше, проблема не в Query.
• Проверяйте select: если он возвращает новый объект без мемоизации, Devtools покажет обновление данных, даже если query.state.data не менялась.
• Включите notifyOnChangeProps: ['data', 'error'], чтобы убедиться, что Query не гоняет лишние уведомления.
• Используйте React.unstable_Tracing или startTransition (React 18) для тяжелых ререндеров, чтобы Devtools не мешали профайлу.

Стратегии оптимизации

• staleTime > 0 + refetchOnWindowFocus: false хорошо подходит для страниц, куда пользователь часто возвращается по кнопке «Назад».
• gcTime: Infinity удобно для справочников, но следите за персистерами: devtools покажут общий объём через Cache size.
• Если нужно удерживать прошлые данные между ключами (например, списки с фильтрами), используйте keepPreviousData: true и смотрите в Devtools, как меняется status (будет pending с isPreviousData: true).
• Для SSR/Hydration сравнивайте dataUpdatedAt до и после dehydrate() — Devtools подсветит, если данные сбрасываются на клиенте.

Дебаг мутаций

• Вкладка Mutations показывает failureCount и meta. Если там пусто, значит не передали meta в useMutation.
• Для повторного запуска мутации вручную нажмите «Run mutation». Это полезно при тестировании idempotent API.
• mutation.reset() очищает ошибку и статус, но данные оптимистичного обновления вам нужно откатить вручную через onError.
• Частая причина двойных вызовов — mutate внутри useEffect без массива зависимостей; Devtools покажет очередь из одинаковых мутаций.

Производительность больших таблиц

• Включите suspense: true + useDeferredValue, чтобы React батчил обновления гигантских таблиц после получения данных.
• При потоковых обновлениях (WebSocket/Server-Sent Events) используйте queryClient.setQueryData с structuralSharing: (prev, next) => fastDeepEqual(prev, next) или false, если шаринг дороже пересоздания.
• Подключите виртуализацию (@tanstack/react-virtual) и смотрите, как Observers уменьшаются до одного списка вместо сотен строковых компонентов.
• В Devtools можно нажать Refetch во время скролла, чтобы проверить, не проседает ли FPS при одновременном обновлении и виртуализации.

Настройка Devtools в Storybook

addDecorator(Story => (
  <QueryClientProvider client={queryClient}>
    <Story />
    <ReactQueryDevtools initialIsOpen={true} position="top" />
  </QueryClientProvider>
));

• Добавьте отдельный сторис «Debug/React Query» с ReactQueryDevtoolsPanel, чтобы дизайнеры могли сами смотреть на данные.
• Комбинируйте с storybook-addon-performance, чтобы сравнивать FPS при разных опциях staleTime.

Интеграция с профайлерами

• React Profiler + Devtools: ставьте маркеры (performance.mark) в subscribe, чтобы на таймлайне видеть моменты fetch.
• Chrome Performance: фильтруйте по react-query в логах (console.time('rq fetch')) и сравнивайте с сетью.
• Lighthouse/CWV: Devtools помогут понять, почему при переходе на страницу происходит двойной запрос (обычно refetchOnReconnect).

Типовые сценарии расследования

• «Запрос всегда refetch при переходе между вкладками» — откройте настройки Devtools, отключите Focus Refetching, а затем настройте refetchOnWindowFocus: false.
• «Иногда отображаются устаревшие данные» — сравните dataUpdatedAt и staleTime, убедитесь, что нет фонового retry.
• «Инфинит-скролл дублирует страницы» — в Devtools переключитесь на Infinite Query, проверьте pageParam в ключе и hasNextPage.
• «Оптимистичный апдейт затирает кеш» — в вкладке Mutations проверьте onMutate / context, убедитесь, что queryClient.setQueryData не перезаписывает весь массив.

FAQ: что смотреть в первую очередь

• Высокий failureCount → проверяем retry и таймауты.
• Observers > ожидаемого → компонент пересоздаёт queryKey.
• Status: fetching без Network-запроса → запрос отменён и перезапущен (проверьте abortController).
• GC срабатывает рано → слишком маленький gcTime, увеличьте или держите placeholderData.

Бонус: эмуляция плохой сети

if (import.meta.env.DEV) {
  queryClient.setDefaultOptions({
    queries: {
      retryDelay: attempt => Math.min(1000 * attempt, 5000),
      networkMode: 'offlineFirst',
    },
  });
}

Совместите с Chrome Network Throttling и наблюдайте в Devtools, как растёт failureCount. Это помогает подобрать реалистичные retry.