404 страницы и NotFound-компоненты

TanStack Router предоставляет мощный и гибкий механизм маршрутизации, позволяющий точно управлять состояниями приложения, включая обработку страниц, которых не существует в маршрутах. Важной частью любой современной веб-приложения является корректная обработка ситуаций, когда пользователь переходит по несуществующему URL. В TanStack Router это реализуется через NotFound-компоненты и маршруты уровня «catch-all».

Настройка маршрута для страницы 404

Для отображения страницы 404 создается маршрут с path: '*' или с использованием специального свойства errorElement. В TanStack Router рекомендуется использовать компонент NotFound на уровне корневого маршрута или дочерних маршрутов для точного контроля над областями приложения, где требуется обработка неизвестных маршрутов.

import { createRouter, RouterProvider } from '@tanstack/router';
import App from './App';
import HomePage from './pages/HomePage';
import NotFoundPage from './pages/NotFoundPage';

const router = createRouter({
  routes: [
    {
      path: '/',
      element: <App />,
      children: [
        { path: '/', element: <HomePage /> },
        {
          path: '*',
          element: <NotFoundPage />
        },
      ],
    },
  ],
});

export default function Root() {
  return <RouterProvider router={router} />;
}

В этом примере маршрут с path: '*' будет отрабатывать для всех URL, не совпадающих с другими маршрутами, и показывать компонент NotFoundPage.

Использование errorElement для глобальной обработки ошибок

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

import ErrorPage from './pages/ErrorPage';

const router = createRouter({
  routes: [
    {
      path: '/',
      element: <App />,
      errorElement: <ErrorPage />, // глобальный обработчик ошибок
      children: [
        { path: '/', element: <HomePage /> },
        { path: '/about', element: <AboutPage /> },
      ],
    },
  ],
});

Если пользователь перейдет на несуществующий маршрут, TanStack Router вызовет компонент ErrorPage, передав объект ошибки, содержащий информацию о маршруте и типе ошибки. Внутри компонента можно проверить тип ошибки:

function ErrorPage({ error }) {
  if (error instanceof RouteError) {
    if (error.status === 404) {
      return <NotFoundPage />;
    }
    return <div>Произошла ошибка: {error.message}</div>;
  }
  return <div>Неизвестная ошибка</div>;
}

Вложенные маршруты и локальные NotFound-компоненты

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

const dashboardRoutes = [
  { path: '/', element: <DashboardHome /> },
  { path: '/stats', element: <DashboardStats /> },
  { path: '*', element: <DashboardNotFound /> }, // локальная 404
];

const router = createRouter({
  routes: [
    {
      path: '/',
      element: <App />,
      children: [
        { path: '/', element: <HomePage /> },
        { path: '/dashboard', element: <DashboardLayout />, children: dashboardRoutes },
        { path: '*', element: <NotFoundPage /> }, // глобальная 404
      ],
    },
  ],
});

Здесь глобальная 404 срабатывает для любых URL, не относящихся к домашней странице или панели управления, а DashboardNotFound обрабатывает ошибки только внутри маршрутов /dashboard.

Доступ к параметрам маршрута и контексту ошибки

NotFound-компоненты могут использовать хук useMatch или useRouteError для получения информации о маршруте, который не был найден, и для кастомизации отображения страницы.

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

function NotFoundPage() {
  const error = useRouteError();
  return (
    <div>
      <h1>Страница не найдена</h1>
      <p>Вы пытались перейти по адресу: {error?.location?.pathname}</p>
    </div>
  );
}

Это позволяет динамически выводить информацию о неправильном URL и, при необходимости, предлагать ссылки на существующие страницы.

Рекомендации по структуре

  • Размещать глобальный NotFound-компонент на корневом уровне маршрутов.
  • Для вложенных маршрутов создавать локальные NotFound-компоненты, чтобы пользователь видел корректный контекст.
  • Использовать errorElement для обработки всех типов ошибок маршрутизации, включая 404 и ошибки данных.
  • Не смешивать path: '*' и конкретные маршруты на одном уровне без явной структуры, чтобы избежать непредсказуемого поведения.

Поведение при серверном рендеринге

При SSR важно учитывать, что сервер должен возвращать HTTP-статус 404 для страниц NotFound. TanStack Router поддерживает передачу статуса через объект ошибки:

throw new RouteError({
  status: 404,
  message: 'Страница не найдена',
});

Это позволяет корректно интегрироваться с серверной логикой и SEO.

Советы по оптимизации UX

  • Добавлять ссылки на главные разделы приложения и поиск на странице 404.
  • Сохранять стиль приложения в NotFound-компонентах, чтобы пользователь не чувствовал разрыва интерфейса.
  • При больших приложениях использовать локальные NotFound-компоненты для модулей, чтобы 404 страница отображалась контекстно.

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

Оглавление