Общий поток SSR

1. На сервере создайте router и вызовите await router.load(), передав URL из запроса.
2. Выполните router.dehydrate() и передайте результат в HTML.
3. На клиенте создайте router с теми же настройками и вызовите router.hydrate(dehydratedState).
4. Отрендерьте <RouterProvider router={router} />.

Дополнительные нюансы

• Для нескольких одновременных запросов повторно используйте один и тот же routeTree, но создавайте новый router и context на каждый HTTP-запрос.
• Передавайте в initialState не только location, но и matches, если хотите сократить повторную работу router.load на клиенте.
• Если используете router.options.context, формируйте серверный контекст (cookies, user, feature flags) синхронно до router.load, чтобы матчи могли сразу читать его в beforeLoad.
• В React 18 оборачивайте клиентский hydrateRoot в startTransition, чтобы Suspense-переходы были плавнее.

// server.ts
const router = createRouter({ routeTree, context })
await router.load({
  initialState: {
    location: createMemoryHistoryLocation(request.url),
  },
})
const dehydrated = router.dehydrate()
const html = renderToString(
  <RouterProvider router={router} />
)

// client.tsx
const router = createRouter({ routeTree, context })
router.hydrate(window.__ROUTER_STATE__)
hydrateRoot(document, <RouterProvider router={router} />)

SSR + TanStack Query

Частый паттерн — прогонять loaders и React Query вместе, чтобы не дублировать fetch-логику.

// server.ts
const queryClient = new QueryClient()
const router = createRouter({
  routeTree,
  context: { queryClient },
})

await router.load({
  preload: true,
  initialState: {
    location: createMemoryHistoryLocation(request.url),
  },
})

const dehydratedRouter = router.dehydrate()
const dehydratedQuery = dehydrate(queryClient)

return renderToString(
  <RouterProvider router={router} context={{ dehydratedQuery }} />
)

На клиенте: сначала hydrate(dehydratedRouter), затем queryClient.hydrate(dehydratedQuery) и только потом hydrateRoot.

Инкрементальная гидратация

• Используйте router.load({ preload: true }) на сервере, чтобы подготовить дочерние маршруты до первого байта.
• Для частичного SSR отдавайте минимальный HTML + router.dehydrate(), а остальной UI догружайте через router.preloadRoute после hydrateRoot.
• Когда нужно отложить тяжёлые match-компоненты, используйте lazyRouteComponent + route.options.staleTime, чтобы не перезапрашивать данные при последующей клиентской навигации.

Prefetch стратегий

• router.preloadRoute — ручное предзагружение.
• preload="viewport" — загрузка при попадании ссылки в viewport.
• beforeLoad + router.load() позволяют подготавливать данные перед переходом (например, в background task).

Умные подсказки

• Link принимает preload, preloadDelay, preloadMaxAge, preloadGcMaxAge — комбинируйте их, чтобы не перегружать сеть.
• router.preloadRoute можно вызывать из useEffect, подписываясь на события скролла и предугадывая переходы.
• Для маршрутов с большими бандлами используйте lazy(() => import('./route')) в createRoute. Префетч автоматически вытянет и код, и данные.
• В компонентах-меню держите router.buildLocation({ to: '/dashboard' }) и передавайте его в router.preloadRoute(...), чтобы прогревать варианты query-параметров.
• Для отмены долгих запросов в prefetch/loader обязательно пробрасывайте signal в fetch-клиент.

Prefetch из React Query

Если вы используете TanStack Query: вызывайте queryClient.prefetchQuery внутри loader, затем queryClient.dehydrate.

const postsRoute = createFileRoute('/posts')({
  beforeLoad: async ({ context }) => {
    await context.queryClient.prefetchQuery({
      queryKey: ['posts', 'list'],
      queryFn: () => fetchPosts(),
      staleTime: 60_000,
    })
  },
})

Так как beforeLoad выполняется и на сервере, и на клиенте, этот код автоматически работает и для SSR, и для клиентского префетча.

Префетч по событиям

• defaultPreload, defaultPreloadDelay, defaultPreloadStaleTime и defaultPreloadMaxAge на createRouter(...) задают глобальную стратегию прогрева.
• Подпишитесь на router.subscribe(...) и замеряйте, сколько времени занял preload; результаты можно сохранять в метриках и динамически регулировать агрессивность префетча.
• При использовании Service Worker можно класть URL будущего маршрута в postMessage, чтобы воркер скачал API и статику параллельно.

Работа офлайн

• router.options.defaultPreloadStaleTime можно увеличить, чтобы данные считались актуальными дольше.
• Кэшируйте результаты loaders в IndexedDB и возвращайте синхронно, пока сеть недоступна.
• Используйте navigator.onLine и router.invalidate() при восстановлении соединения.

Пошаговая стратегия

1. В loader сначала читайте кэш (IndexedDB/Cache Storage). Если данные найдены и свежие — возвращайте их как fallback.
2. Параллельно запускайте сетевой запрос. Если он завершается успешным ответом — обновляйте кэш и вызывайте router.invalidate() для маршрута.
3. В офлайн-баннере подписывайтесь на window.addEventListener('online', ...) и инициируйте router.invalidate() или router.load(), чтобы догрузить свежие данные.
4. Для критичных маршрутов держите статический fallback-компонент в errorComponent, чтобы сразу показывать офлайн-состояние.

Интеграция с Service Worker

• Проксируйте запросы к /router-data/* и храните ответы в Cache Storage.
• Сохраняйте результат router.dehydrate() в IndexedDB после каждого успешного load, чтобы клиент мог стартовать с последнего известного состояния без сети.
• В воркере отправляйте clients.matchAll и шлите сообщение router:refresh, которое на клиенте вызывает router.invalidate().

Работа с background sync

Если маршрут триггерит мутацию, регистрируйте navigator.serviceWorker.ready.then(sw => sw.sync.register('sync-post')), а в onSubmit возвращайте optimistic UI. Когда sync завершается, вызывайте router.invalidate() или queryClient.invalidateQueries.

Streaming / Suspense SSR

• Возвращайте defer из loaders и используйте renderToPipeableStream (React 18).
• Клиент продолжит подгружать данные через Suspense.

const invoiceRoute = createRoute({
  getParentRoute: () => invoicesRoute,
  path: '$invoiceId',
  loader: async () => ({
    invoicePromise: fetchInvoice(),
    audit: await fetchAuditSync(),
  }),
  component: () => (
    <Suspense fallback={<Skeleton />}>
      <InvoiceDetails />
    </Suspense>
  ),
})

• При SSR важно сериализовать router state через router.dehydrate(), чтобы клиент продолжил ожидать те же pending-данные.
• В renderToPipeableStream используйте onShellReady для отправки HTML сразу после готовности критического маршрута и onAllReady для закрытия стрима.

Handling Not Found и Redirect

• На сервере ловите redirect и отвечайте статусом 302/307.
• router.notFound() можно интегрировать с ответом 404.

Советы

• throw redirect({ to: '/login', statusCode: 302 }) работает как на сервере, так и на клиенте, поэтому используйте единую функцию requireAuth.
• В SSR окружении оборачивайте router.load в try/catch, чтобы корректно обработать redirect/notFound и выставить HTTP-статус.
• Для динамического 404 (например, когда сущность не найдена) возвращайте throw notFound({ resetScroll: false }), чтобы не сбрасывать позицию, если пользователь уже был на странице.
• Заполните router.options.defaultNotFoundComponent, чтобы не дублировать 404-разметку во всех ветках дерева.

Конфигурация history

• Для SSR требуется memory history (createMemoryHistory), который TanStack Router создает автоматически при router.load({ initialState }).
• На клиенте используется createBrowserHistory.
• Чтобы гидратация была детерминированной, сервер и клиент должны использовать одинаковый routeTree и сопоставимый context.
• При использовании HashRouter (createHashHistory) на клиенте не забудьте передать history: createHashHistory() в createRouter, иначе гидратация сломается.
• В проектах с Turbopack/Vite сервером держите отдельный createMemoryHistory({ initialEntries: [request.url] }), если нужно симулировать push/pop до рендера.

Чек-лист

• Сервер вызывает router.load() перед рендером.
• Состояние сериализуется и гидратируется без потерь.
• Prefetch включен для критических маршрутов.
• Offline-стратегия (кэш или запасной UI) задокументирована.
• Redirect и 404 корректно обрабатываются на сервере.
• router.dehydrate() и queryClient.dehydrate() синхронно сохраняются и восстанавливаются.
• Service Worker (если есть) знает про маршруты и токены.
• Suspense/streaming сценарии протестированы в slow 3G профиле.