10. Suspense и Error Boundaries

TanStack Query v5 тесно интегрируется с React 18 Suspense и Error Boundaries, позволяя строить декларативные экраны загрузки/ошибок. Ниже собраны практики, которые обычно остаются за кадром в базовых примерах.

useSuspenseQuery

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

const Article = ({ slug }: { slug: string }) => {
  const { data } = useSuspenseQuery(articleQuery(slug));
  return <ArticleBody article={data} />;
};

export const ArticlePage = ({ slug }: { slug: string }) => (
  <ErrorBoundary fallback={<ErrorState />}>
    <Suspense fallback={<ArticleSkeleton />}>
      <Article slug={slug} />
    </Suspense>
  </ErrorBoundary>
);

• Хук бросает Promise/Error, когда данные не готовы — это перехватывается ближайшим Suspense/ErrorBoundary.

• Возвращает только { data } (без статусных флагов). Для расширенных данных используйте useQuery + suspense: true.

• Suspense бросает только до первой успешной загрузки. Далее при фоновых refetch’ах состояние не сбрасывается в fallback — вместо этого обновления проходят прозрачно. Если вам нужно намеренно “пересуспендить” компонент при refetch, установите throwOnError: true и временно сбрасывайте кэш через queryClient.invalidateQueries.
• useSuspenseQuery потребляет опции enabled, select, placeholderData, retry. retry по умолчанию продолжает выполняться до тех пор, пока Suspense не перестанет кидать Promise, поэтому при длинных или нестабильных запросах имеет смысл ограничить retry: 1 и добавить кнопку ручного повторного запроса.
• Если нужно получить статусные флаги (isFetching, errorUpdatedAt), комбинируйте useSuspenseQuery с useQueryClient().getQueryState(queryKey) и подпиской через queryClient.getQueryData.

suspense: true в useQuery

const { data } = useQuery({
  ...profileQuery(id),
  suspense: true,
  useErrorBoundary: true,
});

• suspense: true заставляет useQuery вести себя как useSuspenseQuery.
• Можно комбинировать с select, placeholderData, enabled.
• networkMode: 'always' заставит запрос продолжать работу даже при оффлайне и Suspense будет показывать offline fallback. Полезно для “ожидаемого” ожидания, например, загрузки больших файлов.
• retryOnMount: false вместе с suspense: true предотвращает повторную суспензию при ремоунте, если данные всё ещё недоступны (актуально для client-side routing, когда пользователь возвращается на страницу назад).
• Помните про throwOnError. Если вернуть функцию, можно тонко решить, какие ошибки идут через Error Boundary, а какие показываются локально:

  useQuery({
  ...paymentIntentQuery(),
  suspense: true,
  throwOnError: error => error.code !== 'OTP_REQUIRED',
  });
  

Настройка Error Boundary

<QueryErrorResetBoundary>
  {({ reset }) => (
    <ErrorBoundary onReset={reset} fallbackRender={({ resetErrorBoundary }) => (
      <RetryView onRetry={resetErrorBoundary} />
    )}>
      <Suspense fallback={<Spinner />}>
        <Todos />
      </Suspense>
    </ErrorBoundary>
  )}
</QueryErrorResetBoundary>

• QueryErrorResetBoundary предоставляет reset, который сбрасывает состояние ошибки всех дочерних запросов.
• Внутри ErrorBoundary вызывайте resetErrorBoundary, чтобы повторно попытаться загрузить данные.
• useErrorBoundary: (error) => Boolean(error?.response?.status === 500) полезно, когда часть ошибок стоит обрабатывать inline, а часть пробрасывать наружу.
• Если нужно сбрасывать только конкретный запрос, вызывайте queryClient.resetQueries({ queryKey, exact: true }) внутри onReset.

Селекторы и Suspense

select выполняется до того, как Suspense снимет ожидание, поэтому можно безопасно маппить данные:

const { data: todoTitles } = useSuspenseQuery({
  ...todosQuery(),
  select: todos => todos.map(t => t.title),
});

Зависимые Suspense запросы

const { data: user } = useSuspenseQuery(userQuery(id));
const { data: projects } = useSuspenseQuery({
  ...projectsQuery(user.teamId),
  enabled: Boolean(user.teamId),
});

Если enabled: false, Suspense не будет ждать запрос (он просто не запустится).

• Для цепочек запросов не забывайте про placeholderData. Оно позволяет отрендерить минимальную форму интерфейса и избежать лишнего мигания:

  const { data: projects } = useSuspenseQuery({
  ...projectsQuery(user.teamId),
  enabled: Boolean(user.teamId),
  placeholderData: keepPreviousData,
  });
  

• Когда зависимость может часто менять queryKey, используйте structuralSharing (по умолчанию включён) чтобы реакт не делал полный re-render.

Вложенные Suspense

• Можно строить границы любого уровня, чтобы скелетоны занимали ровно ту область, где идёт загрузка.
• Помещайте тяжёлые секции (<Sidebar />) в отдельный Suspense, чтобы не блокировать основной контент.
• SuspenseList помогает контролировать порядок появления секций: revealOrder="forwards" показывает элементы по мере готовности, сохраняя UX.
• Для ленивых модалок комбинируйте React.lazy(() => import('./Chart')) + Suspense, а данные подгружайте через useSuspenseQuery внутри ленивого компонента.

SSR и suspense

• На сервере React 18 поддерживает потоковую отдачу с Suspense. В сочетании с dehydrate можно выдавать частично готовые страницы.
• Для Next.js App Router используйте use server/use client разделение + <Suspense>.
• На сервере Suspense работает только для компонентов, в которых запросы уже были префетчены: используйте await queryClient.prefetchQuery() перед dehydrate. В противном случае сервер не знает, что нужно ждать, и вернёт fallback ещё до данных.
• Используйте serverPrefetch (в Remix/Next loaders) чтобы не дожидаться Suspense на клиенте. Клиентская граница всё равно нужна для последующих переходов.

Error recovery

• useErrorBoundary может быть функцией: useErrorBoundary: (error) => error.status === 404.
• Для нефатальных ошибок показывайте inline-статусы (status === 'error') без Error Boundary.
• Для многостраничных Layout’ов полезно иметь Error Boundary на уровне AppShell, но при этом ставить локальные границы внутри критичных участков (например, список задач). Это позволяет падать только части дерева.
• Совмещайте ErrorBoundary с startTransition, если после восстановления вы переводите пользователя на другой маршрут:

  const handleRetry = () => {
  startTransition(() => {
    resetErrorBoundary();
    navigate('/dashboard');
  });
  };
  

Диагностика

• Devtools покажет, что запрос «suspended» (индикатор S).
• Если видите бесконечный Suspense, проверьте, не бросает ли select ошибку или не завис ли queryFn.
• В Devtools можно включить Show Offline, чтобы проверить, как ведёт себя Suspense при window.navigator.onLine = false.
• Для тестов используйте renderWithClient + await waitFor(() => screen.getByText(...)): Suspense внутри React Testing Library требует оборачивания тестируемого компонента в Suspense и ErrorBoundary.

useSuspenseInfiniteQuery

const {
  data,
  fetchNextPage,
  hasNextPage,
} = useSuspenseInfiniteQuery({
  queryKey: ['feed'],
  queryFn: ({ pageParam = 0 }) => fetchFeed(pageParam),
  getNextPageParam: lastPage => lastPage.nextCursor,
});

• Suspense ждёт первую страницу, но не ожидает следующие. Поэтому skeleton показывается один раз, а затем используйте кнопки/IntersectionObserver.
• Для бесконечных лент удобно оборачивать кнопку “Ещё” в <Suspense fallback={<InlineSpinner />}>, чтобы при загрузке следующей пачки не блокировать весь список.

Фоновый refetch без “мигания”

• staleTime — главный инструмент управления тем, насколько часто Suspense будет срабатывать. Если значение высокое, то при фокусе вкладки пользователь не увидит повторный fallback.
• Пара placeholderData: previousData + suspense: true предотвращает пустой экран при смене параметров пагинации.
• Используйте queryClient.ensureQueryData(queryOptions) в эффектах или роутерах, чтобы подогревать кэш до маунта компонента. Тогда Suspense вообще не понадобится.

Хелперы для маршрутизации

• В React Router 7 можно вызывать defer и Await. TanStack Query всё ещё полезен: loader делает await queryClient.ensureQueryData, а в компоненте вы спокойно читаете useSuspenseQuery и получаете синхронный доступ.
• В Next.js App Router помните, что useSuspenseQuery работает только в клиентских компонентов ('use client'). Для серверных частей используйте queryClient.fetchQuery и передавайте данные пропсами.

Мутабельные сценарии

• После успешной мутации вызывайте queryClient.invalidateQueries до того, как компонент успеет посетить Suspense, если хотите пересуспендить. Либо используйте setQueryData для мгновенного обновления UI.
• Для оптимистичных апдейтов с Suspense особенно важно вернуть rollbackOnError, иначе Error Boundary покажет ошибку, но список останется в оптимистичном состоянии.

Чеклист отладки

• Проверяйте, что у Error Boundary есть resetKeys. Иначе повторный заход на страницу с тем же queryKey может сразу падать.
• Следите за тем, какие ошибки вы реально хотите “гасить”. Например, 401/403 часто лучше перехватывать на уровне queryFn и редиректить.
• Если Suspense мешает отладке, временно отключайте через suspense: false и проверяйте status в компоненте. После фикса возвращайте обратно.
• Продвинутый вариант — создать кастомный SuspenseBoundary компонент, в котором будут заложены общие fallback, логирование и счётчики (Sentry, Datadog).