Параметр navigateFallback и navigateFallbackWhitelist

Библиотека Sw-precache используется для автоматической генерации сервис-воркера, который обеспечивает кэширование ресурсов веб-приложения и работу в оффлайн-режиме. Одними из ключевых инструментов для управления маршрутизацией являются параметры navigateFallback и navigateFallbackWhitelist. Они позволяют точно настроить поведение сервис-воркера при навигационных запросах.

navigateFallback задаёт URL, на который сервис-воркер будет перенаправлять навигационные запросы, если запрашиваемый ресурс не найден в кэше. Это особенно важно для одностраничных приложений (SPA), где маршрутизация осуществляется на стороне клиента.

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

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'index.html',
    'styles/*.css',
    'scripts/*.js'
  ],
  navigateFallback: '/index.html'
});

В этом примере все навигационные запросы, которые не соответствуют ни одному статическому файлу, будут перенаправлены на index.html. Таким образом, SPA сможет корректно обработать маршрутизацию на клиенте без ошибок 404.

Ключевые особенности:

  • Перехватывает только навигационные запросы (Request.mode === 'navigate').
  • Работает как универсальный fallback для всех страниц, не указанных явно в кэше.
  • Позволяет обеспечить корректное отображение SPA при оффлайн-доступе или при обновлении ресурсов.

Параметр navigateFallbackWhitelist используется совместно с navigateFallback и задаёт регулярные выражения, определяющие, какие навигационные запросы должны быть перенаправлены на fallback-URL. Это позволяет исключить из перенаправления определённые URL, например, API-запросы или внешние страницы.

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

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'index.html',
    'styles/*.css',
    'scripts/*.js'
  ],
  navigateFallback: '/index.html',
  navigateFallbackWhitelist: [/^\/app\//]
});

В этом случае только запросы, URL которых начинается с /app/, будут перенаправлены на index.html. Запросы к /api/ или внешним ресурсам останутся нетронутыми и вернут ошибки сервера, если ресурс отсутствует.

Особенности и нюансы:

  • При отсутствии navigateFallbackWhitelist все навигационные запросы, не совпадающие с кэшем, будут использовать fallback.
  • Регулярные выражения должны быть тщательно подобраны, чтобы не нарушить работу других частей приложения.
  • Использование whitelist помогает избегать конфликтов с API-запросами и сторонними URL.

Взаимодействие navigateFallback и navigateFallbackWhitelist

Эти два параметра работают вместе, создавая гибкую стратегию навигации:

  1. Сервис-воркер проверяет, находится ли запрашиваемый URL в кэше.
  2. Если нет, проверяется, соответствует ли URL хотя бы одному регулярному выражению из navigateFallbackWhitelist.
  3. Если соответствует, запрос перенаправляется на navigateFallback.
  4. Если не соответствует, возвращается стандартный ответ браузера (обычно ошибка 404).

Это позволяет создавать точечную маршрутизацию для SPA с исключением нежелательных перенаправлений.

Примеры типичных сценариев

1. SPA с несколькими маршрутами

swPrecache.write('service-worker.js', {
  staticFileGlobs: ['dist/**.*'],
  navigateFallback: '/dist/index.html',
  navigateFallbackWhitelist: [/^\/dist\//]
});

Все маршруты приложения внутри /dist/ корректно перенаправляются на index.html, а внешние ресурсы остаются доступными напрямую.

2. SPA с API-запросами

swPrecache.write('service-worker.js', {
  staticFileGlobs: ['public/**/*.*'],
  navigateFallback: '/public/index.html',
  navigateFallbackWhitelist: [/^\/pages\//]
});

Запросы к /api/ или /assets/ не попадают под перенаправление, что предотвращает ошибки при взаимодействии с сервером.

Практические рекомендации

  • Всегда комбинировать navigateFallback с navigateFallbackWhitelist, если есть внешние маршруты или API-запросы.
  • Проверять регулярные выражения на соответствие только нужным URL, чтобы избежать бесконечных перенаправлений.
  • Использовать абсолютные или корректно относительные пути для navigateFallback.
  • Тестировать оффлайн-режим и работу сервис-воркера на всех маршрутах приложения, чтобы убедиться, что все страницы SPA корректно обрабатываются.

Понимание и правильная настройка этих параметров позволяют обеспечить корректное функционирование SPA в оффлайн-режиме, контролировать перенаправления и исключать из fallback нежелательные маршруты, делая сервис-воркер более гибким и безопасным.

Оглавление