Определение маршрутов через файлы

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

Файловая структура становится отражением структуры URL, а каждый компонент маршрута подключается автоматически.

Пример базовой структуры проекта:

src/
  routes/
    index.jsx
    about.jsx
    users/
      index.jsx
      [userId].jsx
  • index.jsx в корне папки routes соответствует маршруту /.
  • about.jsx → /about.
  • Папка users формирует базовый путь /users.
  • Файл [userId].jsx представляет динамический сегмент маршрута, соответствующий /users/:userId.

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

Использование квадратных скобок [param] в имени файла создаёт динамический параметр маршрута. Пример:

// src/routes/users/[userId].jsx
import { useParams } from '@tanstack/router';

export default function UserProfile() {
  const { userId } = useParams();
  
  return (
    <div>
      <h1>Профиль пользователя {userId}</h1>
    </div>
  );
}
  • useParams возвращает объект с ключами, соответствующими именам файлов [userId].
  • Можно создавать несколько параметров: [userId]/posts/[postId].jsx → /users/:userId/posts/:postId.

Подключение маршрутов

Файловая система подключается через функцию createFileRouter, которая автоматически сканирует папку маршрутов:

import { createFileRouter } from '@tanstack/router';
import { FileRouterProvider } from '@tanstack/router';

import * as routeFiles from './routes/*.{jsx,js}';

const router = createFileRouter({ routeFiles });

export default function App() {
  return <FileRouterProvider router={router} />;
}
  • Паттерн *.{jsx,js} позволяет подключать все файлы с компонентами маршрутов.
  • createFileRouter строит иерархию маршрутов на основе структуры папок и имён файлов.

Nested Routes и Layouts

Файловый подход отлично сочетается с вложенными маршрутами.

src/routes/
  dashboard/
    index.jsx
    settings.jsx
    layout.jsx
  • layout.jsx автоматически используется как Layout-компонент для всех вложенных маршрутов.
  • index.jsx → /dashboard.
  • settings.jsx → /dashboard/settings.

Пример Layout-компонента:

// src/routes/dashboard/layout.jsx
import { Outlet } from '@tanstack/router';

export default function DashboardLayout() {
  return (
    <div>
      <nav>Меню Dashboard</nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
  • Outlet отображает дочерний маршрут.
  • Можно создавать несколько уровней вложенности с собственными Layout-компонентами.

Index-файлы и маршруты по умолчанию

Файл index.jsx служит маршрутом по умолчанию в папке.

  • Если папка содержит index.jsx и другие файлы, то index.jsx рендерится при переходе на базовый путь папки.
  • Позволяет задавать landing page для секции приложения, а остальные файлы служат подмаршрутами.

Catch-all и Not Found

Для обработки всех остальных маршрутов можно использовать файл с именем [...all].jsx:

// src/routes/[...all].jsx
export default function NotFound() {
  return <h1>Страница не найдена</h1>;
}
  • [...all] захватывает все маршруты, которые не совпали с другими файлами.
  • Используется для отображения страницы 404 или редиректов.

Автоматическое подключение Data Fetching

Файловая структура позволяет связывать data loader и маршруты прямо через файлы:

// src/routes/users/[userId].jsx
import { useLoader } from '@tanstack/router';

export const loader = async ({ params }) => {
  const res = await fetch(`/api/users/${params.userId}`);
  return res.json();
};

export default function UserProfile() {
  const user = useLoader();
  return <div>{user.name}</div>;
}
  • Функция loader автоматически вызывается при рендере маршрута.
  • Можно использовать динамические параметры и передавать их в API.

Преимущества файлового подхода

  1. Прозрачная структура маршрутов — URL отражает папки и файлы.
  2. Меньше ручной конфигурации — не нужно создавать массив объектов маршрутов.
  3. Поддержка динамических сегментов и вложенных Layout.
  4. Автоматическое подключение data loaders и компонентов.
  5. Упрощение масштабирования — добавление нового маршрута требует лишь создания файла в нужной папке.

Советы по организации файлов

  • Использовать папки для группировки маршрутов по смыслу.
  • Динамические маршруты [param] оставлять внутри соответствующей папки.
  • Layout-файлы всегда именовать layout.jsx для автоматического наследования.
  • Index-файлы служат стартовой точкой секции или приложения.
  • Catch-all [...all].jsx оставлять в корне папки routes для глобальной обработки 404.

Итоговая структура для крупного приложения

src/routes/
  index.jsx
  about.jsx
  dashboard/
    layout.jsx
    index.jsx
    settings.jsx
    analytics.jsx
  users/
    layout.jsx
    index.jsx
    [userId].jsx
    [userId]/
      posts.jsx
      [postId].jsx
  [...all].jsx
  • Все маршруты четко отражают URL-структуру.
  • Layout-и распределяются по папкам.
  • Динамические сегменты и catch-all обеспечивают гибкость.

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

Оглавление