Router Store

TanStack Router хранит состояние маршрутизации в собственном сторе (тонкая обертка над Zustand). Его можно читать и подписываться на изменения для построения UI вне компонента маршрута, для тулбаров, заголовков страниц или интеграции с аналитикой.

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

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

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

Дополнительно доступен router.state.matchesById, что полезно для быстрых lookup-ов без перебора массива.

const router = useRouter()
const currentUserId = router.state?.matchesById['/users/$userId']?.params.userId

Контекст router

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

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

context доступен в loader, beforeLoad, action, component через Route.useContext():

const { auth } = Route.useContext()

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

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) }
  })(),
}) satisfies RootRouteOptions<RouterContext>

Используйте satisfies для безопасной проверки структуры. В тестах можно подменять контекст через router.update({ context: { ...router.options.context, auth: mockAuth }, }).

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

• 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) => ...) — низкоуровневая подписка (очищайте вручную). Удобно для service-workers, логгеров или redux-адAPTERов.
• router.store — объект Zustand-like, можно использовать для интеграции с DevTools.

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

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

Глобальные события

router.events.on({
  onBeforeLoad: (event) => log(event),
  onLoad: (event) => analytics.track('route_loaded', event),
  onResolved: () => console.log('done'),
})

События помогают для трекинга, метрик и спиннеров на уровне приложения.

Практические сценарии:

• onBeforeNavigate — валидация/отмена перехода (например, несохранённые формы).
• onLoad + performance.mark — измерение TTI по маршрутам.
• onResolved + router.store.setState — единый индикатор загрузки.

Не забудьте отписаться:

const unsub = router.events.subscribe('onBeforeLoad', handler)
return () => unsub()

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

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

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

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

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

Пример с Zustand

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

router.events.on({
  onResolved: ({ toLocation }) => {
    if (toLocation.pathname.startsWith('/settings')) {
      useThemeStore.getState().toggle()
    }
  },
})

Пример для Redux DevTools

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

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

Debug

• Включите router.options.debug = true.
• Подключите RouterDevtools, вкладка Router State.
• Используйте useRouterState({ select: (state) => state.location }) внутри custom hooks для логирования изменений.
• window.router = router в dev-режиме позволяет вручную вызывать router.navigate из консоли.
• Включите persist: true в router.store при отладке оффлайн-сценариев.
• router.store.subscribe(console.table) — быстрый способ увидеть эволюцию состояния (не забудьте удалить).

if (import.meta.env.DEV) {
  router.store.subscribe((state) => {
    console.debug('[router]', state.location.pathname, state.status)
  })
}

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

• Управление модальными окнами: храните location.state.modal = 'editUser' и рендерьте модалку вне маршрутов, подписавшись на useRouterState.
• Оптимистичные переходы: в onBeforeLoad сохраняйте event.next.location в analytics, чтобы UI сразу показывал skeleton нового маршрута.
• Синхронизация с native-stack: подписывайтесь на router.events.onNavigate и прокидывайте пути в мобильную оболочку.
• Prefetch подсказок: в onRouteMatch запрашивайте подсказки через router.load({ preload: true }), чтобы на hover линка данные уже были в кэше.

Чек-лист

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