Корневой маршрут и его особенности

В TanStack Router корневой маршрут является основой всей маршрутизации приложения. Он задаёт структуру, от которой строятся все дочерние маршруты, и определяет базовую конфигурацию навигации. Обычно корневой маршрут не содержит конкретного пути (или задаётся как '/'), но служит контейнером для вложенных маршрутов и общих компонентов, таких как layout, контекст или обработчики ошибок.

Определение корневого маршрута

Корневой маршрут создаётся с помощью функции createRoute или createRootRoute в зависимости от версии библиотеки. Важно указать ключевые свойства:

  • path – путь маршрута. Для корневого маршрута часто используют '/'.
  • component – компонент React, который будет рендериться на этом маршруте.
  • children – массив дочерних маршрутов.
  • errorComponent – компонент для отображения ошибок внутри корневого маршрута.
  • loader – асинхронная функция для загрузки данных перед рендерингом компонента.

Пример базового корневого маршрута:

import { createRootRoute } from '@tanstack/router';
import AppLayout from './layouts/AppLayout';

export const rootRoute = createRootRoute({
  path: '/',
  component: AppLayout,
  children: [],
  errorComponent: () => <div>Произошла ошибка</div>,
});

Здесь AppLayout обычно содержит общие элементы интерфейса, такие как шапка, боковое меню или футер.

Дочерние маршруты и их наследование

Все дочерние маршруты корневого маршрута автоматически наследуют свойства родителя, если они явно не переопределены:

  • layout – общий layout корневого маршрута будет использоваться для всех дочерних.
  • errorComponent – обработка ошибок может быть глобальной, определённой на уровне корня.
  • loader – данные, загруженные на корневом уровне, доступны во всех вложенных маршрутах через контекст маршрута.

Пример вложенных маршрутов:

import { createRoute } from '@tanstack/router';
import HomePage from './pages/HomePage';
import ProfilePage from './pages/ProfilePage';

export const homeRoute = createRoute({
  path: '/',
  component: HomePage,
});

export const profileRoute = createRoute({
  path: '/profile',
  component: ProfilePage,
});

rootRoute.children = [homeRoute, profileRoute];

В этом примере HomePage и ProfilePage рендерятся внутри компонента AppLayout благодаря наследованию layout.

Загрузка данных на корневом маршруте

Корневой маршрут позволяет централизованно загружать данные, которые нужны на большинстве страниц. Функция loader выполняется до рендера компонента и может возвращать промис с данными:

export const rootRoute = createRootRoute({
  path: '/',
  component: AppLayout,
  loader: async () => {
    const user = await fetch('/api/current-user').then(res => res.json());
    return { user };
  },
});

Эти данные доступны в дочерних маршрутах через хук useLoaderData():

import { useLoaderData } from '@tanstack/router';

function ProfilePage() {
  const { user } = useLoaderData();
  return <div>Привет, {user.name}</div>;
}

Обработка ошибок на корневом уровне

Корневой маршрут может содержать глобальный errorComponent, который перехватывает ошибки всех вложенных маршрутов. Это особенно важно для предотвращения падения всего приложения при сбое отдельного компонента или загрузки данных.

Пример использования:

export const rootRoute = createRootRoute({
  path: '/',
  component: AppLayout,
  errorComponent: ({ error }) => (
    <div>Ошибка приложения: {error.message}</div>
  ),
});

Если дочерний маршрут вызовет ошибку, она будет поймана на уровне корня и отображена через errorComponent.

Навигация и ссылки на корневой маршрут

Корневой маршрут также задаёт базовый путь для построения всех ссылок в приложении. В TanStack Router используется система именованных маршрутов, что позволяет ссылаться на маршруты по ключу, а не по строковому пути. Это повышает стабильность навигации при изменении URL:

import { useNavigate } from '@tanstack/router';

function Header() {
  const navigate = useNavigate();
  
  return <button onCl ick={() => navigate({ to: 'homeRoute' })}>Главная</button>;
}

В этом случае homeRoute – это ключ дочернего маршрута корневого.

Особенности работы с layout

Корневой маршрут часто используется для определения layout приложения. В TanStack Router layout может быть вложенным: корневой маршрут задаёт глобальный layout, а дочерние маршруты могут добавлять свои специфические layout-компоненты. При рендеринге компонента маршрута TanStack Router автоматически объединяет все layout-уровни.

function AppLayout({ children }) {
  return (
    <div>
      <Header />
      <main>{children}</main>
      <Footer />
    </div>
  );
}

Каждый дочерний маршрут вставляется в {children}, что создаёт единый визуальный каркас приложения.

Итоги по корневому маршруту

  • Корневой маршрут задаёт структуру всего приложения.
  • Он может содержать глобальный layout, обработку ошибок и загрузку данных.
  • Дочерние маршруты наследуют его свойства, что упрощает поддержку и централизует логику.
  • Использование loader на корне позволяет делить данные между всеми страницами.
  • Глобальный errorComponent обеспечивает централизованную обработку ошибок.
  • Корневой маршрут формирует базовый путь и ключевую навигацию в приложении.

Корневой маршрут является не просто контейнером, а фундаментом, на котором строится маршрутизация, layout и логика данных для всего приложения TanStack Router.

Оглавление