TanStack Router

TanStack Router — это современная библиотека для маршрутизации в приложениях на React, ориентированная на типобезопасность, гибкость и мощную интеграцию с асинхронными данными. Она обеспечивает более строгую и предсказуемую работу с маршрутами, чем традиционные решения, позволяя строить сложные структуры страниц и управлять состоянием навигации на высоком уровне.

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

Маршруты в TanStack Router создаются с использованием объекта Route, где каждому маршруту задаются путь (path) и компонент (element). Простейший пример определения маршрута выглядит следующим образом:

import { Router, Route } from '@tanstack/react-router';
import HomePage from './pages/HomePage';
import AboutPage from './pages/AboutPage';

const routes = [
  new Route({
    path: '/',
    element: <HomePage />,
  }),
  new Route({
    path: '/about',
    element: <AboutPage />,
  }),
];

const router = new Router({ routes });

Здесь Router управляет всей логикой маршрутизации, а массив routes задаёт все доступные маршруты приложения.

Вложенные маршруты и layout

Одной из сильных сторон TanStack Router является поддержка вложенных маршрутов. Для создания вложенной структуры используется свойство children у маршрута. Это позволяет определить общий layout и одновременно управлять его вложенными страницами.

const dashboardRoute = new Route({
  path: '/dashboard',
  element: <DashboardLayout />,
  children: [
    new Route({ path: 'analytics', element: <AnalyticsPage /> }),
    new Route({ path: 'settings', element: <SettingsPage /> }),
  ],
});

В данном примере DashboardLayout будет отображаться для всех дочерних маршрутов /dashboard/analytics и /dashboard/settings. При этом компоненты дочерних маршрутов рендерятся внутри layout через <Outlet />.

Динамические сегменты и параметры

TanStack Router поддерживает динамические сегменты URL через двоеточие. Параметры маршрута можно использовать для передачи данных в компонент:

const userRoute = new Route({
  path: '/user/:userId',
  element: ({ params }) => <UserProfile userId={params.userId} />,
});

Здесь params.userId автоматически содержит значение сегмента URL, что позволяет работать с динамическими данными.

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

Для интеграции с асинхронными данными TanStack Router предоставляет возможность использовать loader и action функции. loader выполняется при переходе на маршрут и позволяет заранее получить данные:

const postRoute = new Route({
  path: '/posts/:postId',
  element: PostPage,
  loader: async ({ params }) => {
    const response = await fetch(`/api/posts/${params.postId}`);
    return response.json();
  },
});

Загруженные данные доступны в компоненте через хук useLoaderData.

Навигация и ссылки

Для навигации между маршрутами используется компонент <Link> и функция router.navigate. Link обеспечивает клиентскую навигацию без перезагрузки страницы:

<Link to="/about">О нас</Link>

Для программной навигации внутри компонентов можно использовать:

import { useRouter } from '@tanstack/react-router';

function goToHome() {
  const router = useRouter();
  router.navigate('/');
}

Работа с ошибками маршрутов

TanStack Router позволяет задавать обработку ошибок на уровне маршрута через errorElement. Это особенно полезно для отображения страниц 404 или ошибок загрузки данных:

const profileRoute = new Route({
  path: '/profile/:id',
  element: ProfilePage,
  loader: async ({ params }) => {
    const user = await fetchUser(params.id);
    if (!user) throw new Error('Пользователь не найден');
    return user;
  },
  errorElement: <ErrorPage />,
});

Любые ошибки в loader или action автоматически передаются в errorElement.

Защита маршрутов и условная навигация

Для реализации защиты маршрутов можно использовать хуки и проверку данных в loader:

const protectedRoute = new Route({
  path: '/dashboard',
  element: DashboardPage,
  loader: async () => {
    const user = await fetchCurrentUser();
    if (!user) throw new Error('Не авторизован');
    return user;
  },
});

Таким образом, пользователь не сможет попасть на защищённый маршрут без авторизации, а ошибки обрабатываются централизованно через errorElement.

Поддержка TypeScript и типобезопасность

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

interface UserParams {
  userId: string;
}

const userRoute = new Route<{ params: UserParams }>({
  path: '/user/:userId',
  element: UserPage,
});

TypeScript будет проверять наличие обязательного параметра userId и его тип на этапе компиляции.

Интеграция с React Suspense

Для оптимизации загрузки данных и компонентов TanStack Router поддерживает Suspense. Асинхронные загрузки маршрутов можно оборачивать в <Suspense> для отображения индикатора загрузки:

<Suspense fallback={<Loading />}>
  <RouterProvider router={router} />
</Suspense>

Это позволяет создавать плавный UX, особенно при работе с крупными приложениями и тяжелыми компонентами.

Настройка переходов и анимаций

TanStack Router предоставляет возможность контролировать поведение при навигации через хуки onBeforeChange, onAfterChange и другие. Это позволяет реализовать кастомные анимации переходов и проверку условий перед сменой маршрута.

router.onBeforeChange((from, to) => {
  if (to.path === '/restricted') {
    return false; // блокировка перехода
  }
});

Такой подход обеспечивает гибкую логику маршрутизации на любом уровне приложения.

Заключение

Использование TanStack Router в React-приложениях позволяет создавать сложные маршруты с вложенной структурой, динамическими параметрами, асинхронной загрузкой данных и строгой типизацией. Его возможности по управлению состоянием навигации, обработке ошибок и интеграции с Suspense делают библиотеку мощным инструментом для профессиональной разработки современных веб-приложений.

Оглавление