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

Эта глава объединяет три production-сценария:

• сохранять query cache между перезагрузками
• работать без сети
• корректно использовать TanStack Query в SSR/RSC

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

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({
  defaultOptions: {
    queries: {
      gcTime: 24 * 60 * 60 * 1000,
    },
  },
})

persistQueryClient({
  queryClient,
  persister: createSyncStoragePersister({
    storage: window.localStorage,
  }),
  maxAge: 24 * 60 * 60 * 1000,
  buster: 'v1',
})

Важно:

• gcTime должен быть не меньше maxAge, иначе данные могут удалиться раньше восстановления.
• При изменении схемы данных повышайте buster.

Что сохранять, а что нет

Персистить стоит:

• справочники
• профиль и настройки
• кэшированные списки, если они реально нужны offline

Осторожно с:

• чувствительными данными
• огромными infinite list
• временными admin/debug запросами

Используйте shouldDehydrateQuery, если нужно фильтровать.

Async storage

Для React Native/Expo используется async persister:

• createAsyncStoragePersister
• AsyncStorage или собственный storage adapter

Идея та же, отличается только storage backend.

onlineManager и focusManager

Можно переопределять источники событий:

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

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

  return () => {
    window.removeEventListener('online', () => setOnline(true))
    window.removeEventListener('offline', () => setOnline(false))
  }
})

Это особенно полезно для:

• React Native
• Electron
• embedded webview
• кастомных offline-first окружений

networkMode

Доступные режимы:

• online
• always
• offlineFirst

Обычно:

• для query подходит online
• для offline-first приложений часть query и mutation переводят в offlineFirst

Пауза и возобновление мутаций

После восстановления из persister и возврата сети полезно:

await queryClient.resumePausedMutations()

Это особенно важно, если вы храните offline queue.

SSR: базовый порядок действий

1. Создайте новый QueryClient на сервере.
2. Выполните prefetchQuery или ensureQueryData.
3. Вызовите dehydrate(queryClient).
4. Передайте state в HydrationBoundary.
5. На клиенте используйте те же query factories.

App Router и Server Components

Современный рекомендуемый подход:

• серверный компонент выступает как loader
• он делает prefetch
• затем отдаёт HydrationBoundary
• клиентский компонент читает тот же query через useQuery

Пример:

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query'

export default async function PostsPage() {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery(postsOptions())

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostsClient />
    </HydrationBoundary>
  )
}

Почему на клиенте часто лучше useQuery, а не useSuspenseQuery

Если данные уже были префетчены и гидратированы, обычный useQuery обычно достаточно хорош:

• данные будут доступны сразу
• вы избежите лишних сложностей Suspense

Suspense всё ещё полезен, но не обязателен для уже прогретых запросов.

Практические рекомендации

• На сервере всегда новый QueryClient.
• В браузере один стабильный экземпляр.
• Старайтесь не сериализовать лишнее.
• Для SSR задавайте осмысленный staleTime, чтобы клиент сразу после hydration не делал лишний refetch.
• Для offline-first сценариев заранее продумайте, какие query действительно должны жить после перезагрузки.