Опции роутера

Universal Router — это гибкая и минималистичная библиотека маршрутизации для JavaScript, которая позволяет определять маршруты через объекты и функции. Настройка роутера осуществляется через опции, передаваемые при создании экземпляра UniversalRouter. Разбор этих опций позволяет максимально эффективно использовать возможности маршрутизатора в проектах различной сложности.

routes

routes — это ключевая опция, определяющая структуру маршрутов. Она представляет собой массив объектов, каждый из которых описывает отдельный маршрут. Структура объекта маршрута может включать следующие свойства:

  • path — строка с шаблоном пути (например, /users/:id).
  • action — функция, вызываемая при совпадении маршрута. Может возвращать значение, промис или результат рендеринга.
  • children — массив дочерних маршрутов для вложенной маршрутизации.
  • name — уникальное имя маршрута, полезное для генерации ссылок.
  • data — произвольные данные, доступные в action.

Пример использования:

import UniversalRouter from 'universal-router';

const routes = [
  {
    path: '/',
    action: () => 'Главная страница'
  },
  {
    path: '/users/:id',
    action: ({ params }) => `Пользователь с ID ${params.id}`
  },
  {
    path: '/about',
    children: [
      {
        path: '/team',
        action: () => 'Наша команда'
      }
    ]
  }
];

const router = new UniversalRouter(routes);

context

context — объект, который передается в каждый action маршрута. Используется для хранения общих данных, сервисов или зависимостей, доступных во всех маршрутах. Это позволяет избежать импорта общих модулей в каждой функции отдельно.

Пример:

const router = new UniversalRouter(routes, {
  context: {
    apiClient,
    userService
  }
});

router.resolve('/users/42').then(result => {
  console.log(result); // Использует apiClient и userService внутри action
});

resolveRoute

resolveRoute — функция, которая вызывается для каждого маршрута перед тем, как выполнить его action. Она позволяет реализовать кастомную логику сопоставления маршрута или предварительную обработку. Функция получает объект маршрута, context и параметры.

Пример:

const router = new UniversalRouter(routes, {
  resolveRoute: async (route, context, params) => {
    if (route.requiresAuth && !context.user.isAuthenticated) {
      return '/login';
    }
    return route;
  }
});

Эта опция особенно полезна для проверки прав доступа или редиректов перед выполнением действия маршрута.

errorHandler

errorHandler — функция для обработки ошибок при разрешении маршрута. Она вызывается, если промис, возвращаемый action, отклоняется, либо если маршрут не найден. Это позволяет централизованно управлять ошибками и реализовывать собственные страницы 404 или страницы ошибок сервера.

Пример:

const router = new UniversalRouter(routes, {
  errorHandler: (error, context) => {
    if (error.status === 404) {
      return 'Страница не найдена';
    }
    return 'Произошла ошибка на сервере';
  }
});

stringifyQuery

stringifyQuery — функция для преобразования объекта с параметрами запроса в строку URL. Позволяет настраивать формат query-параметров, например, использовать собственный сериализатор или кодировщик.

Пример:

const router = new UniversalRouter(routes, {
  stringifyQuery: params => {
    return Object.keys(params)
      .map(key => `${key}=${encodeURIComponent(params[key])}`)
      .join('&');
  }
});

matchRoot

matchRoot — булева опция, определяющая, будет ли роутер пытаться сопоставить маршрут с корнем (/) при отсутствии явного совпадения. Значение по умолчанию — true.

const router = new UniversalRouter(routes, { matchRoot: false });

Если установлено false, маршруты будут разрешаться только при точном совпадении.

baseUrl

baseUrl — базовый URL, который добавляется к всем маршрутам. Это удобно для приложений, развернутых не в корне домена. Например, если приложение находится по пути /app, можно указать baseUrl: '/app', чтобы все маршруты автоматически строились относительно этого пути.

const router = new UniversalRouter(routes, { baseUrl: '/app' });

Принципы комбинирования опций

  1. Контекст + resolveRoute — позволяет создать централизованную логику авторизации, подгрузки данных и редиректов.
  2. errorHandler + action — гарантирует, что ошибки не прерывают работу приложения и корректно отображаются пользователю.
  3. baseUrl + stringifyQuery — обеспечивает консистентное формирование ссылок и маршрутов независимо от окружения.

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

  • Разделять маршруты и контекст: маршруты определяются отдельно в виде массива объектов, контекст — отдельно, для удобного тестирования и повторного использования.
  • Использовать resolveRoute для middleware-логики: проверка прав, логирование, условные редиректы.
  • Всегда определять errorHandler для предотвращения необработанных исключений и корректного отображения страниц ошибок.
  • stringifyQuery и baseUrl применять только при необходимости кастомизации маршрутов и формирования ссылок на стороне клиента.

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

Оглавление