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

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

Директории и их назначение

1. src/routes — маршруты приложения В этой директории хранятся все определения маршрутов. Хорошая практика — создавать поддиректории для каждого крупного раздела приложения. Например:

src/routes/
  ├─ index.tsx
  ├─ dashboard/
  │   ├─ index.tsx
  │   └─ analytics.tsx
  ├─ users/
  │   ├─ index.tsx
  │   └─ [userId].tsx
  └─ settings/
      ├─ index.tsx
      └─ profile.tsx

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

  • Каждый файл маршрута экспортирует объект маршрута через createRoute.
  • Файлы с динамическими сегментами пути используют синтаксис [param], что упрощает связывание URL и параметров.

2. src/components — компоненты интерфейса Компоненты, используемые в маршрутах, хранятся отдельно. Это позволяет не смешивать логику маршрутизации и представление. Подкатегории можно создавать для крупных разделов приложения:

src/components/
  ├─ layout/
  │   └─ MainLayout.tsx
  ├─ ui/
  │   ├─ Button.tsx
  │   └─ Modal.tsx
  └─ users/
      ├─ UserCard.tsx
      └─ UserForm.tsx

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

  • Компоненты маршрутов должны быть максимально независимыми.
  • Общие элементы интерфейса, такие как шапка или меню, располагаются в layout.

3. src/router.ts — корневой роутер Файл router.ts содержит иерархию всех маршрутов и создаёт экземпляр роутера с помощью createRouter. Пример базовой структуры:

import { createRouter } from '@tanstack/router'
import { rootRoute } from './routes'
import { dashboardRoute } from './routes/dashboard'
import { usersRoute } from './routes/users'
import { settingsRoute } from './routes/settings'

export const router = createRouter({
  routeTree: rootRoute.addChildren([
    dashboardRoute,
    usersRoute,
    settingsRoute,
  ]),
})

Основные правила:

  • Все маршруты импортируются из соответствующих файлов.
  • Использование метода addChildren формирует иерархию маршрутов, что упрощает навигацию и управление доступом.

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

TanStack Router позволяет легко работать с динамическими сегментами URL:

  • Файл [userId].tsx автоматически связывает сегмент URL с параметром userId.
  • Внутри маршрута доступ к параметрам осуществляется через хук useParams:
import { useParams } from '@tanstack/router'

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

Рекомендации по организации:

  • Для каждого динамического маршрута создается отдельный файл.
  • Если динамический маршрут имеет вложенные маршруты, их удобно помещать в поддиректорию с названием [param].

Лэйауты и вложенные маршруты

TanStack Router поддерживает вложенные маршруты с собственными лэйаутами. Например:

src/routes/dashboard/index.tsx       // основной лэйаут dashboard
src/routes/dashboard/analytics.tsx   // вложенный маршрут
export const dashboardRoute = rootRoute.addChild({
  path: 'dashboard',
  component: DashboardLayout,
  children: [
    {
      path: 'analytics',
      component: AnalyticsPage,
    },
  ],
})

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

  • Лэйауты позволяют определять общий интерфейс для группы маршрутов.
  • Дочерние маршруты автоматически рендерятся внутри <Outlet /> родительского компонента.

Разделение логики и данных

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

  • Файл маршрута отвечает только за путь и компонент.
  • Файл loader’а или service занимается загрузкой данных:
// src/routes/users/[userId].ts
export const userLoader = async ({ params }) => {
  const response = await fetch(`/api/users/${params.userId}`)
  return response.json()
}

В компоненте маршрута подключается loader через TanStack Router:

import { useLoaderData } from '@tanstack/router'

export default function UserPage() {
  const user = useLoaderData<typeof userLoader>()
  return <div>{user.name}</div>
}

Советы по масштабированию

  1. Четкая иерархия папок облегчает навигацию по проекту.
  2. Использование динамических сегментов упрощает работу с параметрами URL.
  3. Лэйауты для групп маршрутов минимизируют дублирование кода интерфейса.
  4. Разделение загрузки данных и компонентов обеспечивает чистоту кода и облегчает тестирование.
  5. Согласованная схема именования файлов — [param].tsx для динамических маршрутов, index.tsx для корневых и вложенных маршрутов.

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

Оглавление