12. Персистентность, офлайн и SSR

TanStack Query может переживать перезагрузку страницы, работать без сети и подготавливать данные на сервере.

Персистентность кеша

import { QueryClient } from '@tanstack/react-query';
import { persistQueryClient } from '@tanstack/react-query-persist-client';
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';

const queryClient = new QueryClient();

persistQueryClient({
  queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
    key: 'app-cache-v5',
    throttleTime: 1000,
  }),
  maxAge: 24 * 60 * 60 * 1000, // 24h
  hydrateOptions: {
    defaultOptions: {
      queries: {
        staleTime: 5 * 60 * 1000,
      },
    },
  },
  dehydrateOptions: {
    shouldDehydrateQuery: ({ state }) => state.status === 'success',
  },
});

• Состояние кеша сохраняется в localStorage и восстанавливается при следующем запуске.
• Используйте buster (версию схемы), чтобы сбрасывать устаревшие данные.
• Передавайте hydrateOptions/dehydrateOptions, чтобы выравнивать staleTime и сразу помечать критичные запросы как просроченные.
• throttleTime защищает сторедж от частых записей при бурных мутациях, а serialize/deserialize помогают компрессировать данные (например, через superjson).
• Если требуется лениво восстанавливать кеш, вызывайте persistQueryClientRestore вручную при инициализации, а persistQueryClientSave — после входа пользователя.
• Не забудьте отключить персистентность для чисто пользовательских настроек, чтобы не мешать GC: gcTime запросов должен быть ≥ maxAge.

Тонкая фильтрация при сериализации

const shouldKeep = (query) => {
  const isLargeList = query.queryHash.startsWith('products');
  return !isLargeList; // example: не пишем тяжёлые списки
};

persistQueryClient({
  queryClient,
  persister,
  dehydrateOptions: {
    shouldDehydrateQuery: shouldKeep,
  },
});

• Для списков можно сохранять только «страницу 1», а остальные данные добирать по мере захода пользователя.
• Ошибки по умолчанию не сериализуются: укажите serializeError/deserializeError, если хотите ресурфейсить сообщения без дополнительного запроса.

IndexedDB и шифрование

• На десктопе лучше использовать createIDBPersister (из @tanstack/query-async-storage-persister), чтобы не упереться в лимит localStorage.
• Для приложений с PII заверните persistQueryClient в слой шифрования (например, crypto.subtle), но помните, что дешифровка должна быть синхронной или выполнена до hydrate.

Async storage (React Native / Expo)

import AsyncStorage from '@react-native-async-storage/async-storage';
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';

const persister = createAsyncStoragePersister({
  storage: AsyncStorage,
  retry: async (err) => {
    await wait(1000);
    return err?.message !== 'QuotaExceededError';
  },
});

• Expo/React Native: ограничьте maxAge, иначе iOS может удалить приложение и сторедж ради места.
• Для платформы Hermes хороша быстрая альтернатива MMKV (react-native-mmkv), но тогда потребуется собственный persister.
• Добавляйте retry с бэкоффом, чтобы переживать QuotaExceededError и временно отключённый Secure Storage.
• Используйте AppState для очередей: как только приложение вновь активно, вызывайте persistQueryClientRestore.

Управление офлайн-состоянием

import { onlineManager, focusManager } from '@tanstack/react-query';

onlineManager.setEventListener(setOnline => {
  window.addEventListener('online', () => setOnline(true));
  window.addEventListener('offline', () => setOnline(false));
});

focusManager.setEventListener(handleFocus => {
  window.addEventListener('visibilitychange', () => handleFocus(!document.hidden));
});

• По умолчанию библиотека использует window.addEventListener, но вы можете адаптировать к Electron/React Native.
• Когда onlineManager сообщает о «офлайне», все запросы переходят в fetchStatus: 'paused' и автоматически продолжатся после восстановления связи.
• React Native: подключите @react-native-community/netinfo и AppState, чтобы сообщать onlineManager о состоянии сети и активности экрана.
• Для приложений на Capacitor/Electron подписывайтесь на IPC-ивенты и перекидывайте их в onlineManager.setOnline.
• Можно подсвечивать UI при помощи onlineManager.subscribe(cb) и ручного queryClient.invalidateQueries, как только сеть вернулась.
• Если нужно опрашивать API даже в фоне (например, на телевизорах), установите focusManager.setFocused(true) и возьмите ответственность за энергопотребление.

Очередь мутаций офлайн

import { persistQueryClientRestore } from '@tanstack/react-query-persist-client';

await persistQueryClientRestore({
  queryClient,
  persister,
  maxAge: Infinity,
});

// useMutation({ networkMode: 'offlineFirst' });

networkMode: 'offlineFirst' заставляет мутацию помещаться в очередь и выполняться после возвращения сети.

• networkMode: 'always' полезен для сервисов, которые обязаны синхронизироваться даже в фоне (например, через Service Worker), но в браузере он будет кидать ошибки при недоступной сети.
• Добавьте meta: { offlineRetry: true } и глобальный mutationCache, чтобы логировать и визуализировать очередь.

const mutationCache = new MutationCache({
  onSuccess: (_data, variables, _ctx, mutation) => {
    if (mutation.meta?.flushOnReconnect) {
      queryClient.invalidateQueries(['invoices']);
    }
  },
});

const queryClient = new QueryClient({ mutationCache });

useMutation(updateInvoice, {
  networkMode: 'offlineFirst',
  meta: { flushOnReconnect: true },
});

• При оптимистичных апдейтах сохраняйте «snapshots» в mutation.meta и восстанавливайте UI, если пользователь закрыл вкладку до синхронизации.
• Для критичных операций (оплата) объединяйте с Background Sync API: при sync событии Service Worker извлекает мутации и выполняет их даже когда вкладка закрыта.

Триггеры повторного рендера после восстановления кеша

• После persistQueryClientRestore вызовите queryClient.resumePausedMutations(), иначе мутации останутся в paused.
• Если после восстановления нужно сразу рефетчить определённые ключи, используйте queryClient.invalidateQueries({ predicate }), пока приложение находится в «сплэше».
• Чтобы избежать мигания UI, читайте isRestoring из своего стора и рендерьте скелет до hydrate.

SSR / SSG

1. Создайте QueryClient на сервере.
2. Выполните prefetchQuery/prefetchInfiniteQuery для нужных данных.
3. Вызовите dehydrate(queryClient).
4. Передайте состояние клиенту и оберните приложение в Hydrate.

export async function render(url: string) {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(appBootstrapQuery());
  const html = renderToString(
    <QueryClientProvider client={queryClient}>
      <Hydrate state={dehydrate(queryClient)}>
        <App url={url} />
      </Hydrate>
    </QueryClientProvider>,
  );
  return html;
}

• Не забывайте об AbortController: если пользователь прервал HTTP-запрос, отмените и соответствующий prefetchQuery, чтобы избежать утечек.
• Для prefetchInfiniteQuery передайте initialPageParam, иначе первая страница может отличаться от клиента.
• dehydrate принимает shouldDehydrateQuery: можно исключить приватные данные и мутации, которые не должны попадать в HTML.
• Настраивайте defaultOptions.queries.gcTime = Infinity на сервере, чтобы сборщик мусора не удалил результаты до момента dehydrate.

Next.js (App Router)

• Используйте QueryClientProvider внутри Providers.
• Для серверных компонентов применяйте dehydrate на уровне маршрута и прокидывайте через HydrationBoundary.
• Для кэширования на сервере комбинируйте с react-cache/cache() из Next.js.
• В generateStaticParams и generateMetadata можно вызывать prefetchQuery, но не забудьте создать независимый QueryClient, чтобы не смешивать данные разных запросов.
• Для серверных действий (server actions) держите QueryClient короткоживущим: создавайте его прямо внутри действия, чтобы не тащить состояние между пользователями.
• Оборачивайте клиентские страницы в HydrationBoundary state={dehydrate(...)} и добавляйте suspense: true, чтобы использовать React Streaming.
• Распределяйте кеш по сегментам: одна страница — один HydrationBoundary, это уменьшит размер HTML и ускорит LCP.

Remix

• В loader создайте QueryClient, выполните prefetchQuery и верните dehydrate.
• В компоненте Route используйте useLoaderData + Hydrate.
• Добавьте shouldRevalidate = false, если данные полностью покрываются react-query и вам не нужен повторный вызов loader.
• Для action возвращайте mutationCache состояние, чтобы клиент знал, что мутация уже выполнена на сервере и не запускал её повторно.

Безопасность и размер кеша

• Не сохраняйте чувствительные данные (токены) в персисторе.
• Используйте serializeError/deserializeError, если хотите сохранять ошибки.
• Следите за размером localStorage: старые записи можно вручную удалять через queryClient.removeQueries.
• Для мультиюзерного клиента сбрасывайте кеш после смены пользователя: queryClient.clear() + persister.removeClient().
• Если нужно хранить токены рефреша, переведите persister в sessionStorage (меньше риск XSS) или используйте ServiceWorker с шифрованием.

Диагностика офлайн-режима

• Devtools показывают paused запросы.
• Добавьте UI-индикатор onlineManager.isOnline(), чтобы сообщать пользователю о состоянии сети.
• Логируйте queryClient.getQueryCache().findAll({ fetchStatus: 'paused' }), чтобы видеть, какие ключи застряли офлайн.
• Используйте onReconnect хук (собственный) и запускайте refetchOnReconnect: false для шумных запросов, иначе при восстановлении сети можно DDOS-нуть API.

Service Worker и персистентность

• В service-worker.js можно подключить тот же persister (через IndexedDB) и восстанавливать кеш прямо в воркере, чтобы отдавать данные из postMessage ещё до загрузки React.
• Комбинируйте с Background Sync API: когда вкладка закрыта, воркер всё ещё способен вызывать queryClient.resumePausedMutations().
• Если используете Workbox, синхронизируйте ключи между workbox.precaching и persistQueryClient, чтобы инвалидировать кеш при развертывании.

Частые паттерны

• Split-кеш: храните только критичные запросы (профиль, настройки). Остальное подгружайте сразу после старта через queryClient.prefetchQuery.
• Warm-up: после hydrate прогоните queryClient.resumePausedMutations и invalidateQueries для «грязных» ключей — пользователь не увидит устаревший контент.
• Offline-first роуты: оборачивайте страницы в компонент, который проверяет onlineManager.isOnline() и либо показывает форму, либо ставит мутации в очередь.
• Аналитика: передавайте meta.analyticsKey во все запросы и отправляйте события, когда paused → fetching, чтобы отслеживать качество сети пользователей.