Обзор объекта конфигурации

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

staticFileGlobs Этот параметр определяет массив шаблонов путей к статическим ресурсам, которые должны быть включены в кэш при установке сервис-воркера. Шаблоны используют синтаксис glob, что позволяет задавать маски, например:

staticFileGlobs: [
  'public/**/*.html',
  'public/css/**/*.css',
  'public/js/**/*.js',
  'public/images/**/*.{png,jpg,gif,svg}'
]

Здесь кэшируются все HTML-файлы, CSS и JS из указанных директорий, а также изображения с перечисленными расширениями.

stripPrefix Позволяет удалить префикс пути при записи в кэш. Это важно, если структура директорий на сервере отличается от корневой структуры приложения. Например:

stripPrefix: 'public/'

В результате в кэше файлы будут храниться относительно корня, без префикса public/.

runtimeCaching Позволяет определять стратегии кэширования для ресурсов, которые не включены в staticFileGlobs, например, для API-запросов. Каждый объект в массиве описывает правило сопоставления URL и стратегию кэширования:

runtimeCaching: [{
  urlPattern: /\/api\/.*$/,
  handler: 'networkFirst'
}]

Доступные стратегии:

  • networkFirst — сначала пытается загрузить ресурс из сети, при неудаче использует кэш;
  • cacheFirst — сначала ищет ресурс в кэше, при отсутствии делает сетевой запрос;
  • fastest — параллельно обращается к сети и кэшу, возвращает первый успешный ответ.

navigateFallback Этот параметр указывает файл, который будет возвращаться при запросе несуществующих URL. Обычно используется для SPA, чтобы направлять все незарегистрированные маршруты на index.html:

navigateFallback: '/index.html'

stripPrefixMulti Позволяет задавать сразу несколько префиксов для удаления при добавлении файлов в кэш. Работает как объект с ключами — префиксами, и значениями — строками, на которые префиксы заменяются:

stripPrefixMulti: {
  'public/': '',
  'build/': ''
}

ignoreUrlParametersMatching Массив регулярных выражений для игнорирования определённых GET-параметров при сравнении URL ресурсов с кэшем. Например:

ignoreUrlParametersMatching: [/^utm_/, /^fbclid$/]

Все параметры, начинающиеся с utm_ или равные fbclid, будут игнорироваться, что позволяет избежать лишнего дублирования ресурсов в кэше.

verbose Флаг логирования процесса генерации сервис-воркера. Значение true включает подробные сообщения, полезные при отладке:

verbose: true

stripPrefixLength Альтернативный способ убрать указанное количество символов с начала пути файла перед добавлением в кэш:

stripPrefixLength: 7

Это удаляет первые 7 символов пути, полезно при унификации структуры URL внутри кэша.

handleFetch Флаг, который указывает, будет ли сервис-воркер перехватывать сетевые запросы. Если false, генератор создаёт сервис-воркер только для предзагрузки ресурсов:

handleFetch: true

directoryIndex Задает имя файла, который будет подставляться, если URL оканчивается слешем. По умолчанию 'index.html':

directoryIndex: 'home.html'

Комбинирование параметров

Все параметры конфигурации можно комбинировать для создания точной стратегии кэширования. Например, можно одновременно кэшировать статику из папки public, игнорировать аналитические GET-параметры и использовать networkFirst для API-запросов:

swPrecache.write('service-worker.js', {
  staticFileGlobs: ['public/**/*.{html,css,js,png,jpg,gif,svg}'],
  stripPrefix: 'public/',
  runtimeCaching: [
    { urlPattern: /\/api\/.*$/, handler: 'networkFirst' }
  ],
  ignoreUrlParametersMatching: [/^utm_/, /^fbclid$/],
  navigateFallback: '/index.html',
  verbose: true
});

Этот подход обеспечивает полное покрытие всех типов ресурсов и гибкое управление поведением кэша при изменении контента и маршрутов.

Особенности работы

  • sw-precache генерирует полностью рабочий сервис-воркер, который автоматически управляет установкой, активацией и очисткой старых кэшей.
  • Параметры runtimeCaching и navigateFallback позволяют поддерживать SPA и динамический контент без потери оффлайн-доступа.
  • Грамотно настроенный stripPrefix упрощает управление URL внутри кэша, особенно при деплое на разных серверах.

Таким образом, объект конфигурации sw-precache является центральным элементом, позволяющим гибко управлять кэшированием и стратегиями работы сервис-воркера.

Оглавление