Структура документации и как ею пользоваться

TanStack Router — это современный роутер для JavaScript-приложений, построенный с акцентом на декларативное описание маршрутов и мощную работу с асинхронными данными. В основе работы лежит концепция маршрутного дерева, где каждый маршрут — это объект с набором свойств, определяющих путь, параметры, вложенные маршруты и асинхронные данные.

Ключевые элементы маршрута:

  • path — строка, определяющая URL-маршрут. Поддерживаются динамические сегменты через :param.
  • component — React-компонент или функция, рендерящая содержимое маршрута.
  • loader — асинхронная функция для загрузки данных перед отображением компонента.
  • children — массив вложенных маршрутов, создающих иерархию.
  • meta — объект для хранения дополнительной информации, например, прав доступа или настроек SEO.

Создание маршрутов

Маршруты строятся декларативно, что позволяет легко управлять сложными иерархиями.

import { createRouter, RouterProvider } from '@tanstack/router';
import Home from './pages/Home';
import Profile from './pages/Profile';
import Settings from './pages/Settings';

const router = createRouter({
  routes: [
    {
      path: '/',
      component: Home,
      children: [
        {
          path: 'profile/:userId',
          component: Profile,
          loader: async ({ params }) => {
            const response = await fetch(`/api/users/${params.userId}`);
            return response.json();
          },
        },
        {
          path: 'settings',
          component: Settings,
        },
      ],
    },
  ],
});

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

  • Вложенные маршруты наследуют путь родителя, что упрощает навигацию и создание сложных интерфейсов.
  • Динамические параметры (:userId) автоматически передаются в loader и компонент через хук useParams().
  • В loader можно выполнять асинхронные запросы, и TanStack Router гарантирует, что данные будут доступны до рендера компонента.

Работа с данными через маршруты

Для асинхронной загрузки данных TanStack Router использует loader и useLoaderData().

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

function Profile() {
  const data = useLoaderData();
  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

Ключевые моменты:

  • loader вызывается до рендера компонента, предотвращая показ пустого состояния.
  • Поддерживаются кеширование и повторное использование данных для оптимизации производительности.
  • Можно комбинировать несколько loader на разных уровнях маршрута, что позволяет создавать сложные страницы с многослойными данными.

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

TanStack Router предоставляет удобные средства для навигации и контроля истории браузера:

  • useNavigate() — хук для программной навигации.
  • Link — компонент для создания ссылок, учитывающий вложенные маршруты.
  • useSearchParams() — хук для работы с query-параметрами.
import { Link, useNavigate } from '@tanstack/router';

function Menu() {
  const navigate = useNavigate();
  
  return (
    <div>
      <Link to="/">Главная</Link>
      <button onCl ick={() => navigate('/settings')}>Настройки</button>
    </div>
  );
}

Особенности:

  • Навигация учитывает вложенную структуру маршрутов и параметры.
  • Поддерживается переход по истории назад и вперед с сохранением состояния.
  • Query-параметры и хэши URL автоматически синхронизируются с состоянием компонентов.

Метаданные и управление доступом

Каждый маршрут может содержать объект meta для хранения пользовательских данных:

{
  path: 'admin',
  component: AdminPanel,
  meta: {
    requiresAuth: true,
    roles: ['admin'],
  },
}
  • Meta позволяет реализовать проверку прав доступа перед рендером компонента.
  • Можно использовать глобальные хук-перехватчики (onBeforeRoute) для авторизации и редиректов.
  • Meta-данные удобно использовать для настройки заголовков страниц, breadcrumbs и других элементов UI.

Работа с вложенными маршрутами

Иерархическая структура маршрутов упрощает управление сложными интерфейсами:

const routes = [
  {
    path: '/',
    component: Layout,
    children: [
      { path: 'dashboard', component: Dashboard },
      { path: 'reports', component: Reports },
    ],
  },
];
  • Родительский компонент (Layout) может рендерить общие элементы интерфейса, например навигацию и sidebar.
  • Дочерние маршруты подставляются в <Outlet />, создавая динамическую область рендера.
  • Вложенные loaders работают каскадно: родительский loader выполняется перед дочерним.

Отладка и инструментирование

TanStack Router предоставляет встроенные возможности для отладки:

  • Поддержка DevTools, позволяющих видеть дерево маршрутов, текущее состояние loaders и параметры URL.
  • Логирование переходов и ошибок.
  • Возможность перехвата событий маршрутизации для аналитики или интеграции с внешними системами.

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

Оглавление