9. Prefetch, Hydration и начальные данные

Предзагрузка и гидратация позволяют отдавать пользователю готовые данные до первого рендера и уменьшать «белые экраны».

Prefetch полезен только тогда, когда вероятность перехода высока и данные достаточно тяжёлые, чтобы окупить запрос заранее.
Hydration имеет смысл, если у вас есть серверный рендер или вы можете заранее положить состояние в <script> и избежать двойного запроса.
Чем короче staleTime, тем быстрее TanStack Query решит перезагрузить даже дегидрированные данные — держите это в голове, чтобы не терять преимущество SSR.

Когда prefetch срабатывает лучше всего

hover/long-press по ссылке или карточке;
элементы в зоне IntersectionObserver (пользователь почти дошёл скроллом);
ожидаемый переход по следующему шагу мастера (в React Router можно запускать prefetch в loader следующего route);
повторное посещение страницы, где есть «холодный» кеш (prefetch позволяет заранее вернуть warm cache, пока пользователь просматривает другой экран).

`prefetchQuery`

await queryClient.prefetchQuery(articleQuery(slug));

Загружает данные и кладёт их в кеш без подписчиков.
Возвращает Promise<void>, поэтому удобно использовать в роутерах (React Router loader, Next.js generateStaticParams).
Фактически вызывает fetchQuery, но подавляет ошибки наружу и не меняет статус активных подписчиков.
Prefetch — идемпотентен: если данные свежие, повторный вызов просто завершится синхронно.

await queryClient.prefetchQuery({
  queryKey: ['article', slug],
  queryFn: () => fetchArticle(slug, { signal }),
  staleTime: 5 * 60_000,
  gcTime: 30 * 60_000,
  meta: { source: 'hover' },
});

В v5 есть единый объект опций: используйте те же поля, что и в useQuery.
Передавайте signal из React Router loader / Remix loader, чтобы отменять запрос, если пользователь уходит со страницы до завершения.
Можно хранить «причину» prefetch в meta, чтобы в Devtools понимать, откуда взялись данные.

Prefetch в роутерах

// React Router v6.22+
export const articleLoader =
  (queryClient: QueryClient) =>
  async ({ params, request }) => {
    const slug = params.slug!;
    await queryClient.ensureQueryData({
      ...articleQuery(slug),
      signal: request.signal,
    });
    return null;
  };

В loader лучше звать ensureQueryData: он вернёт фактические данные и не сделает лишний запрос, если кеш свежий.
Для вложенных роутов можно заранее префетчить дочерние данные через Promise.all, пока родительский loader ещё исполняется.

`dehydrate` / `Hydrate`

// server.tsx
await queryClient.prefetchQuery(articleQuery(slug));
const dehydratedState = dehydrate(queryClient);

// client.tsx
<Hydrate state={dehydratedState}>
  <App />
</Hydrate>

dehydrate сериализует состояние Query Cache.
Передавайте dehydratedState на клиент и оборачивайте приложение в Hydrate.
Данные считаются свежими, пока не истечёт исходный staleTime.
Не все запросы стоит сериализовать: часто удобно исключить очень короткоживущие (gcTime < 5s) или приватные (зависящие от cookie) данные.

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery: query =>
    query.state.status === 'success' &&
    query.queryKey[0] !== 'debug-only',
});

В SSR можно разделить состояние на несколько HydrationBoundary, чтобы догружать тяжёлые блоки лениво и избегать массивных JSON в html.

<HydrationBoundary state={headerState}>
  <Header />
</HydrationBoundary>
<HydrationBoundary state={contentState}>
  <Article />
</HydrationBoundary>

Если данные динамические, используйте initialDataUpdatedAt и удлиняйте staleTime, иначе сразу после гидратации произойдёт refetch и пользователь всё равно увидит двойной запрос.
Следите, чтобы структура ключей совпадала на сервере и клиенте (включая сериализацию параметров). Любое расхождение приведёт к повторному запросу, даже если состояние гидрировано.

Next.js / Remix

В App Router используйте @tanstack/react-query-next-experimental и HydrationBoundary.
В Remix — defer + useLoaderData, затем useQuery с initialData.
В Next.js App Router удобно вызвать prefetchQuery прямо в серверном компонентах и обернуть клиентский компонент в HydrationBoundary:

// app/(blog)/[slug]/page.tsx
export default async function Page({ params }) {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(articleQuery(params.slug));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <ArticleClient slug={params.slug} />
    </HydrationBoundary>
  );
}

Для маршрутов с revalidate = 0 (ISR) нужно синхронизировать staleTime и revalidate: если staleTime слишком большой, клиент не увидит новые данные даже после регенерации страницы.
В Remix можно передать данные как defer({ dehydratedState }), а на клиенте вызвать useLoaderData и HydrationBoundary. Это уменьшит время TTFB, потому что остальная страница может стримиться сразу.

`initialData` vs `placeholderData`

initialData помечает запрос как status: 'success' мгновенно.
placeholderData показывает временное значение, но статус остаётся pending.

useQuery({
  ...articleQuery(slug),
  initialData: () => queryClient.getQueryData(['articles-list'])?.find(a => a.slug === slug),
  initialDataUpdatedAt: () => queryClient.getQueryState(['articles-list'])?.dataUpdatedAt,
});

Таким образом дата обновления совпадает с исходной записью, и staleTime учитывается корректно.

initialData отлично сочетается с Infinity Scroll: можно взять карточку из списка и мгновенно показать страницу детали.
placeholderData полезен для скелетонов: верните облегчённую версию объекта (без тяжёлых полей), чтобы перейти от списка к деталям без «перескока».
С Suspense placeholderData не снимает suspense, а вот initialData позволит обойтись без fallback.
Если placeholderData — функция, не забывайте проверять previousData, чтобы не затирать уже отображаемые значения.

`ensureQueryData`

const article = await queryClient.ensureQueryData(articleQuery(slug));

Выполняет prefetchQuery, но возвращает данные (как fetchQuery), при этом не бросает ошибку, если данные уже загружены и свежие.
Удобно в серверных роутерах.
Лайфхак: оборачивайте несколько ensureQueryData в Promise.all, чтобы сервер мог параллельно подтянуть независимые блоки:

await Promise.all([
  queryClient.ensureQueryData(profileQuery(userId)),
  queryClient.ensureQueryData(recommendationsQuery(userId)),
]);

Если нужно гарантировать, что данные появились в кеше, но не хотите ждать ответа (например, prefetch по hover), можно игнорировать возвращаемое значение и дать запросу доработать в фоне.

Prefetch при наведении

const prefetchArticle = (slug: string) => {
  queryClient.prefetchQuery(articlePreviewQuery(slug), {
    staleTime: 60_000,
  });
};

<Link onMouseEnter={() => prefetchArticle(article.slug)} />

Пользователь получит мгновенный рендер карточки.

Для touch-устройств добавляйте prefetch на onTouchStart, иначе пользователь не успеет «нагреть» кеш.
Следите, чтобы prefetch не вызывался на каждом mousemove: оборачивайте обработчик в lodash/throttle или requestIdleCallback.
Если в списке десятки ссылок, ставьте лимит параллельных prefetch (например, через p-limit), чтобы не DDOS-ить API.

Prefetch по IntersectionObserver

const observer = new IntersectionObserver(entries => {
  entries
    .filter(entry => entry.isIntersecting)
    .forEach(entry => {
      const slug = entry.target.getAttribute('data-slug')!;
      queryClient.prefetchQuery(articlePreviewQuery(slug));
    });
});

Отлично работает для каруселей и лендингов с блоками «ниже fold», потому что пользователь с большой вероятностью докрутит до них.

Начальные данные из `<script>`

<script id="__INITIAL_DATA__" type="application/json">
  {"dehydratedState": {...}}
</script>

На клиенте:

const dehydratedState = JSON.parse(
  document.getElementById('__INITIAL_DATA__')!.textContent!,
);

const queryClient = new QueryClient();
hydrate(queryClient, dehydratedState);

Можно сжимать dehydratedState перед вставкой (например, JSON.stringify(state, (_, value) => value ?? undefined)), чтобы убрать undefined и сократить payload.
Если опасаетесь XSS, сериализуйте JSON через serialize-javascript или devalue.

Работа с `placeholderData`

useQuery({
  ...productQuery(id),
  placeholderData: previousData => previousData ?? skeletonProduct,
});

Можно передавать функцию, которая получает предыдущее значение запроса (если оно было).
Возвращайте облегчённые данные, чтобы избежать вспышек.
placeholderData не попадает в кеш. Если нужно сохранить его в кеше, комбинируйте placeholderData с onSuccess, где вручную вызовете setQueryData.
Списки можно прогревать placeholderData из «соседних» страниц, чтобы при переходе вперёд/назад данные не мигали.

`prefetchInfiniteQuery`

await queryClient.prefetchInfiniteQuery({
  ...feedQuery(userId),
  initialPageParam: null,
});

Не забудьте передать pageParams в dehydrate, иначе клиент не узнает, какие курсоры уже загружены.
В v5 dehydrate автоматически кладёт pageParams, но только если запрос успел завершиться успешно. Если prefetch оборвался, проверьте query.state.fetchStatus.
При гидратации не забудьте передать initialPageParam в useInfiniteQuery — иначе React Query решит, что данных нет, и запустит новый запрос.
Для ленивых списков можно префетчить только первую страницу, а остальные — догружать через prefetchInfiniteQuery в IntersectionObserver, как только пользователь добирается до конца.

9. Prefetch, Hydration и начальные данные

Когда prefetch срабатывает лучше всего

prefetchQuery

Prefetch в роутерах

dehydrate / Hydrate

Next.js / Remix

initialData vs placeholderData

ensureQueryData