Использование с Create React App

Для интеграции TanStack Router с проектом на Create React App необходимо установить пакет через npm или yarn:

npm install @tanstack/router
# или
yarn add @tanstack/router

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

import { createRouter, RouterProvider, Route } from '@tanstack/router';
import { createRoot } from 'react-dom/client';
import App from './App';
import Home from './pages/Home';
import About from './pages/About';

const router = createRouter({
  routeTree: Route({
    path: '/',
    component: App,
    children: [
      Route({ path: '/', component: Home }),
      Route({ path: '/about', component: About }),
    ],
  }),
});

const root = createRoot(document.getElementById('root'));
root.render(<RouterProvider router={router} />);

Структура маршрутов

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

  • Route — основной строительный блок маршрутизации.
  • path — URL-путь маршрута.
  • component — React-компонент, который рендерится при совпадении пути.
  • children — вложенные маршруты, позволяющие строить сложную структуру навигации.

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

Route({
  path: '/dashboard',
  component: DashboardLayout,
  children: [
    Route({ path: '/stats', component: StatsPage }),
    Route({ path: '/settings', component: SettingsPage }),
  ],
});

В этом примере DashboardLayout остаётся на странице, а компоненты StatsPage и SettingsPage рендерятся внутри него в зависимости от подмаршрута.

Навигация между маршрутами

TanStack Router предоставляет хук useNavigate для программного перехода между страницами:

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

function HomeButton() {
  const navigate = useNavigate();
  
  return (
    <button onCl ick={() => navigate('/dashboard/stats')}>
      Перейти к статистике
    </button>
  );
}

Для ссылок используется компонент Link, который предотвращает перезагрузку страницы и работает как стандартный тег <a>:

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

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

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

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

Route({ path: '/user/:userId', component: UserProfile });

В компоненте доступ к параметру осуществляется через хук useParams:

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

function UserProfile() {
  const { userId } = useParams();
  return <div>Профиль пользователя: {userId}</div>;
}

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

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

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

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

В компоненте данные доступны через хук useLoaderData:

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

function PostPage() {
  const post = useLoaderData();
  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  );
}

Такой подход позволяет избегать состояния “loading” внутри компонентов и централизованно управлять асинхронной загрузкой данных.

Обработка ошибок и 404 страницы

Для управления ошибками и страницами, которые не найдены, можно использовать маршруты с errorComponent:

Route({
  path: '/posts/:postId',
  component: PostPage,
  loader: async ({ params }) => fetch(`/api/posts/${params.postId}`).then(res => res.json()),
  errorComponent: PostError,
});

Кроме того, можно задать глобальный 404 маршрут:

Route({ path: '*', component: NotFoundPage });

Состояние и контексты маршрутизатора

TanStack Router позволяет хранить глобальное состояние навигации и использовать его в любом компоненте через контекст маршрутизатора:

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

function CurrentRouteInfo() {
  const router = useRouter();
  return <div>Текущий путь: {router.state.location.pathname}</div>;
}

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

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

В Create React App важно учитывать, что маршрутизатор работает в режиме SPA. Необходимо:

  1. Настроить basename при развертывании в подкаталоге:
const router = createRouter({
  routeTree,
  basename: '/my-app',
});
  1. В файле package.json указать корректный homepage для корректной генерации ссылок при сборке:
"homepage": "https://example.com/my-app"
  1. Обеспечить поддержку fallback на index.html на сервере, чтобы SPA корректно обрабатывала прямые переходы по URL.

Важные преимущества TanStack Router в CRA

  • Вложенная маршрутизация позволяет создавать сложные интерфейсы без избыточного кода.
  • Динамические сегменты делают маршруты универсальными для разных сущностей.
  • Загрузка данных на уровне маршрутов упрощает работу с асинхронными запросами.
  • Глобальное состояние маршрутизатора интегрируется с компонентами без лишнего проп-дриллинга.
  • Интеграция с CRA работает «из коробки» и поддерживает SPA-сценарии.

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

Оглавление