Router Store

TanStack Router хранит состояние маршрутизации во внутреннем store и позволяет подписываться на изменения через useRouterState/router.subscribe. Это удобно для глобального UI (progress bar, breadcrumbs, title) и аналитики.

const status = useRouterState({ select: (s) => s.status })

Основные поля состояния

• location — { pathname, search, hash, state }. Часто удобно мемоизировать только pathname, чтобы не перерендеривать layout при изменении query.
• resolvedLocation — фактический URL после всех нормализаций (удаляйте лишние / именно тут).
• matches — массив активных маршрутов с данными loaders, meta и context.
• status — обычно idle | pending. Можно использовать как флажок для глобальных спиннеров.
• isTransitioning / isLoading — булевы derived-поля, пригодны для disable-кнопок.
• pendingLocation — информация о следующем переходе (например, для оптимистичных UI).
• fetchCount и pendingMatches — показывают, сколько loaders сейчас в полёте.

Контекст router

Контекст задается при создании:

const router = createRouter({
  routeTree,
  context: {
    auth,
    queryClient,
  },
})

context доступен в loader, beforeLoad и в компонентах через Route.useRouteContext():

const { auth } = Route.useRouteContext()

Типизация контекста

interface RouterContext {
  auth: ReturnType<typeof createAuthClient>
  queryClient: QueryClient
  featureFlags: FeatureFlagService
}

export const router = createRouter({
  routeTree,
  context: (() => {
    const auth = createAuthClient()
    const queryClient = new QueryClient()
    return { auth, queryClient, featureFlags: createFlags(auth) }
  })(),
})

В тестах обычно создают отдельный router с тестовым context (фейковые auth/api clients).

Подписки и селекторы

• useRouterState({ select, structuralSharing, equalityFn }) мемоизирует результат и предотвращает перерендер. Возвращайте “плоские” примитивы или мемоизированные объекты.

const { pathname, status } = useRouterState({
  select: ({ location, status }) => ({ pathname: location.pathname, status }),
  equalityFn: (a, b) => a.pathname === b.pathname && a.status === b.status,
})

• router.subscribe((state) => ...) — низкоуровневая подписка (очищайте вручную). Удобно для логгеров или адаптеров внешнего стора.

Лайфхак: если нужно реактивно управлять заголовком страницы, можно сделать кастомный хук:

export function useDocumentTitle() {
  const meta = useRouterState({
    select: (state) => state.matches.at(-1)?.context?.title ?? state.location.pathname,
  })
  useEffect(() => {
    document.title = meta
  }, [meta])
}

Логирование и интеграции

Для метрик обычно достаточно комбинации router.subscribe + router.history.subscribe/listen (в зависимости от history-адаптера). Главный принцип: подписки должны жить в одном “инфраструктурном” модуле и всегда отписываться при размонтировании.

Router API полезные методы

| Метод | Назначение | | — | — | | router.invalidate() | Глобальный refetch всех loaders. | | router.load() | Префетч дерева маршрутов (используется в SSR). | | router.dehydrate() / router.hydrate() | Работа с SSR state. | | router.navigate({ to, search, replace, resetScroll }) | Гибкая навигация с точным контролем поведения скролла. | | router.buildLocation({ to, params, search }) | Получить URL-объект без перехода (для ссылок/OG-тегов). |

const href = router.buildLocation({
  to: '/projects/$projectId',
  params: { projectId },
  search: (old) => ({ ...old, filter }),
})

Интеграция с внешними стейт-менеджерами

• Передавайте клиенты (queryClient, urql) через context.
• Используйте Route.useRouteContext() вместо глобальных синглтонов.
• В beforeLoad можно синхронно читать глобальное состояние (redux store).

Пример с Zustand

const useThemeStore = create((set) => ({ theme: 'light', toggle: () => set(...) }))

const unsub = router.subscribe((state) => {
  if (state.location.pathname.startsWith('/settings')) {
    useThemeStore.getState().toggle()
  }
})

// позже: unsub()

Пример для Redux DevTools

router.subscribe((state) => {
  reduxStore.dispatch(routerStateUpdated(state))
})

Не тащите UI-стор внутрь context: вместо этого пробрасывайте сервисы/клиенты, а сами UI-состояния держите в своих сторах.

Debug

• Подключите RouterDevtools, вкладка Router State.
• Используйте useRouterState({ select: (state) => state.location }) внутри custom hooks для логирования изменений.
• window.router = router в dev-режиме позволяет вручную вызывать router.navigate из консоли.
• При необходимости подпишитесь на router.subscribe в dev и логируйте только нужные поля.

Примеры из практики

• Управление модальными окнами: храните location.state.modal = 'editUser' и рендерьте модалку вне маршрутов, подписавшись на useRouterState.
• Оптимистичные переходы: до navigate сохраняйте target в analytics и показывайте skeleton нового маршрута.
• Синхронизация с native-stack: подписывайтесь на router.history и прокидывайте пути в мобильную оболочку.
• Prefetch подсказок: при hover/touch вызывайте router.preloadRoute({ to }), чтобы данные уже лежали в кэше.

Чек-лист

• Контекст определен один раз и типизирован.
• Компоненты используют useRouterState/useRouteContext, а не глобальные импорты.
• Стор используется для построения глобальных индикаторов загрузки.
• События роутера логируются при необходимости.
• При SSR состояние сериализуется через dehydrate/hydrate.
• Есть отдельный слой для интеграции с внешними сторами (redux/zustand).
• Debug-инструменты включаются только в dev-среде.
• Для сложных селекторов используются equalityFn или кастомные мемоизации.