Breaking changes

Navigo — легковесная библиотека маршрутизации для JavaScript, которая активно развивается. С каждой новой версией могут появляться изменения, которые нарушают обратную совместимость с предыдущими релизами. Важно понимать эти breaking changes, чтобы корректно обновлять существующие проекты.

Удаление поддержки устаревших методов

В последних версиях Navigo были удалены методы, которые ранее позволяли гибко управлять маршрутами:

  • Navigo.add() и Navigo.remove() полностью заменены на централизованную работу через объект маршрутов. Ранее можно было добавлять маршруты динамически на лету. Теперь добавление происходит только через инициализацию экземпляра:

    const router = new Navigo('/');
router.on({
  '/home': () => console.log('Home'),
  '/about': () => console.log('About')
}).resolve();

    Попытка использовать add() вызовет ошибку.

  • Метод navigate(url, absolute) теперь принимает только один аргумент — строку URL. Второй параметр absolute удалён. Пример нового синтаксиса:

    router.navigate('/contact');

Изменения в обработке параметров маршрута

Ранее маршруты поддерживали параметризацию с простым синтаксисом :param. В новых версиях появилась строгая проверка типов и форматирования параметров:

  • Примеры старого синтаксиса:

    router.on('/user/:id', (params) => console.log(params.id));

    Работало для любого значения после :id.

  • Новый синтаксис требует явного указания регулярного выражения для сложных случаев:

    router.on('/user/:id(\\d+)', (params) => console.log(params.id));

    Без указания формата библиотека по умолчанию разрешает только символы [a-zA-Z0-9_-]. Использование старого формата для произвольных строк может приводить к некорректной обработке маршрута.

Изменения в режиме hash и history

Navigo поддерживает два режима маршрутизации — hash и history. В последних версиях были значительные изменения в поведении history API:

  • Старый подход:

    const router = new Navigo(null, true);

    Второй параметр означал использование hash.

  • Новый подход:

    const router = new Navigo({
  strategy: 'hash' // или 'history'
});

    Прежняя форма инициализации с булевым флагом true или false больше не поддерживается.

  • Изменения затрагивают и генерацию ссылок:

    • Методы link() больше не добавляют автоматически # при использовании hash-режима.
    • Следует явно указывать, как формировать URL для внутренних ссылок.

Обновлённая система перехватчиков (hooks)

В новых версиях Navigo внедрена система before/after hooks, которая заменяет устаревшие глобальные события on с колбэками:

  • Старый способ:

    router.on('/dashboard', dashboardHandler);
router.notFound(notFoundHandler);

    После обновления рекомендуется использовать hooks:

    router.on('/dashboard', dashboardHandler)
      .hooks({
        before: (done, params) => {
          // Проверка авторизации
          done();
        },
        after: (params) => console.log('Route finished')
      });

  • Метод notFound() был удалён. Теперь обработка отсутствующих маршрутов осуществляется через on с символом '*':

    router.on('*', () => console.log('Page not found'));

Изменения поведения метода resolve

Метод resolve ранее автоматически вызывал текущий маршрут при инициализации:

router.resolve(); // выполнял обработчик текущего URL

Теперь resolve() не вызывается автоматически при создании экземпляра. Это изменение влияет на приложения, которые рассчитывали на немедленное выполнение маршрута при загрузке страницы. Новая практика:

router.on('/home', homeHandler)
      .on('/about', aboutHandler)
      .resolve(); // явный вызов после всех маршрутов

Устаревшие опции конфигурации

Некоторые опции при инициализации Navigo были удалены или изменены:

Опция Старое поведение Новое поведение
noMatchWarning Логировал в консоль ошибки для несопоставленных маршрутов Опция удалена, теперь контролируется через '*' маршрут
hash Булевый флаг Используется strategy: 'hash' или strategy: 'history'
linksSelector Автоматическая привязка к ссылкам Метод updatePageLinks() теперь используется вручную

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

Итоговые рекомендации для обновления проектов

  1. Переписать инициализацию маршрутов через объект on.
  2. Использовать строгую параметризацию с регулярными выражениями.
  3. Перейти на новый формат strategy вместо булевых флагов hash/history.
  4. Реализовать обработку not found через маршрут '*'.
  5. Явно вызывать resolve() после настройки всех маршрутов.
  6. Использовать hooks before и after вместо устаревших глобальных событий.

Эти изменения требуют внимательного анализа существующего кода перед обновлением версии библиотеки. Правильная адаптация к новым breaking changes позволяет использовать все возможности Navigo без неожиданных ошибок и нарушений логики маршрутизации.

Оглавление