рабочийбокс-webpack-плагин

Workbox предоставляет два плагина веб-пакета : один создает для вас полный сервис-воркер, а другой создает список ресурсов для предварительного кэширования, который внедряется в файл сервис-воркера.

Плагины реализованы в виде двух классов в модуле workbox-webpack-plugin с именами GenerateSW и InjectManifest . Ответы на следующие вопросы помогут вам выбрать правильный плагин и конфигурацию для использования.

Какой плагин использовать

GenerateSW

Плагин GenerateSW создаст для вас файл сервисного работника и добавит его в конвейер ресурсов веб-пакета.

Когда использовать GenerateSW

  • Вы хотите предварительно кэшировать файлы.
  • У вас есть простые потребности в кэшировании во время выполнения.

Когда НЕ использовать GenerateSW

  • Вы хотите использовать другие функции Service Worker (например, Web Push ).
  • Вы хотите импортировать дополнительные сценарии или добавить дополнительную логику для пользовательских стратегий кэширования.

InjectManifest

Плагин InjectManifest сгенерирует список URL-адресов для предварительного кэширования и добавит этот манифест предварительного кэширования в существующий файл Service Worker. В противном случае файл останется как есть.

Когда использовать InjectManifest

  • Вы хотите больше контроля над своим сервисным работником.
  • Вы хотите предварительно кэшировать файлы.
  • Вам необходимо настроить маршрутизацию и стратегии.
  • Вы хотели бы использовать своего сервис-воркера с другими функциями платформы (например, Web Push ).

Когда НЕ использовать InjectManifest

  • Вам нужен самый простой путь добавления сервисного работника на ваш сайт.

Плагин GenerateSW

Вы можете добавить плагин GenerateSW в конфигурацию вашего веб-пакета следующим образом:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

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

Полный набор возможностей конфигурации можно найти в справочной документации .

Плагин InjectManifest

Вы можете добавить плагин InjectManifest в конфигурацию вашего веб-пакета следующим образом:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

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

Полный набор возможностей конфигурации можно найти в справочной документации .

Дополнительная информация

Руководство по использованию плагинов в контексте более крупной сборки веб-пакета можно найти в разделе « Прогрессивное веб-приложение » документации веб-пакета.

Типы

GenerateSW

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

Используйте экземпляр GenerateSW в массиве plugins конфигурации веб-пакета.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

Характеристики

GenerateSWConfig

Характеристики

  • Дополнительные записи манифеста

    (строка | ManifestEntry )[] необязательно

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

  • BabelPresetEnvTargets

    строка[] необязательно

    Значение по умолчанию: ["chrome >= 56"]

    Цели, которые необходимо передать в babel-preset-env при передаче пакета Service Worker.

  • идентификатор кэша

    строка необязательна

    Необязательный идентификатор, добавляемый к имени кэша. Это в первую очередь полезно для локальной разработки, когда несколько сайтов могут обслуживаться из одного источника http://localhost:port .

  • куски

    строка[] необязательно

    Одно или несколько имен фрагментов, соответствующие выходные файлы которых должны быть включены в манифест предварительного кэширования.

  • очисткаУстаревшиекеши

    логическое значение необязательно

    Значение по умолчанию: ложь.

    Должен ли Workbox пытаться идентифицировать и удалить любые прекеши, созданные более старыми несовместимыми версиями.

  • КлиентыПретензия

    логическое значение необязательно

    Значение по умолчанию: ложь.

    Должен ли сервисный работник начинать контролировать существующих клиентов сразу после его активации.

  • индекс каталога

    строка необязательна

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

  • отключить DevLogs

    логическое значение необязательно

    Значение по умолчанию: ложь.

  • dontCacheBustURLsMatching

    RegExp необязательно

    Предполагается, что ресурсы, соответствующие этому значению, имеют уникальную версию через свой URL-адрес и освобождены от обычной очистки HTTP-кеша, которая выполняется при заполнении предварительного кэша. Хотя это и не обязательно, рекомендуется, чтобы, если ваш существующий процесс сборки уже вставляет значение [hash] в каждое имя файла, вы предоставили RegExp, который обнаружит это, поскольку это уменьшит потребление полосы пропускания при предварительном кэшировании.

  • исключать

    (строка | RegExp | функция)[] необязательно

    Один или несколько спецификаторов, используемых для исключения ресурсов из манифеста предварительного кэширования. Это интерпретируется по тем же правилам, что и стандартная опция exclude webpack . Если не указано, значение по умолчанию — [/\.map$/, /^manifest.*\.js$] .

  • исключить куски

    строка[] необязательно

    Одно или несколько имен фрагментов, соответствующие выходные файлы которых следует исключить из манифеста предварительного кэширования.

  • игнорироватьURLParametersMatching

    RegExp[] необязательно

    Любые имена параметров поиска, совпадающие с одним из регулярных выражений в этом массиве, будут удалены перед поиском соответствия предварительному кэшированию. Это полезно, если ваши пользователи могут запрашивать URL-адреса, содержащие, например, параметры URL-адресов, используемые для отслеживания источника трафика. Если не указано, значение по умолчанию — [/^utm_/, /^fbclid$/] .

  • импортскрипты

    строка[] необязательно

    Список файлов JavaScript, которые следует передать в importScripts() внутри сгенерированного файла сервисного работника. Это полезно, если вы хотите, чтобы Workbox создал рабочий файл службы верхнего уровня, но хотите включить некоторый дополнительный код, например прослушиватель push-событий.

  • импортскриптсвиачанкс

    строка[] необязательно

    Одно или несколько имен фрагментов веб-пакета. Содержимое этих фрагментов будет включено в сгенерированный сервис-воркер посредством вызова importScripts() .

  • включать

    (строка | RegExp | функция)[] необязательно

    Один или несколько спецификаторов, используемых для включения ресурсов в манифест предварительного кэширования. Это интерпретируется по тем же правилам, что и стандартная опция include webpack .

  • inlineWorkboxRuntime

    логическое значение необязательно

    Значение по умолчанию: ложь.

    Должен ли код среды выполнения библиотеки Workbox быть включен в сервис-воркера верхнего уровня или разделен на отдельный файл, который необходимо развернуть вместе с сервис-воркером. Разделение среды выполнения означает, что пользователям не придется повторно загружать код Workbox каждый раз, когда изменяется ваш сервис-воркер верхнего уровня.

  • манифестЗаписи

    ManifestEntry [] необязательно

  • манифесттрансформс

    ManifestTransform [] необязательно

    Одна или несколько функций, которые будут последовательно применяться к сгенерированному манифесту. Если также указаны modifyURLPrefix или dontCacheBustURLsMatching , сначала будут применены соответствующие преобразования.

  • Максимальныйфилесизетокачеинбайтес

    номер необязательно

    Значение по умолчанию: 2097152.

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

  • режим

    строка необязательна

    Если установлено значение «производство», будет создан оптимизированный пакет сервисного работника, исключающий информацию об отладке. Если здесь не указано явно, будет использоваться значение mode , настроенное в текущей компиляции webpack .

  • изменитьURLPrefix

    объект необязательный

    Строка сопоставления объекта является префиксом для замещающих строковых значений. Это можно использовать, например, для удаления или добавления префикса пути из записи манифеста, если настройки вашего веб-хостинга не соответствуют настройкам вашей локальной файловой системы. В качестве более гибкой альтернативы вы можете использовать опцию manifestTransforms и предоставить функцию, которая изменяет записи в манифесте, используя любую предоставленную вами логику.

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

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • навигацияРезервный вариант

    строка необязательна

    Значение по умолчанию: ноль.

    Если указано, все запросы навигации для URL-адресов, которые не кэшируются предварительно, будут выполняться с использованием HTML-кода по указанному URL-адресу. Вы должны передать URL-адрес HTML-документа, который указан в вашем манифесте предварительного кэширования. Это предназначено для использования в сценарии одностраничного приложения, в котором вы хотите, чтобы все элементы навигации использовали общий HTML-код оболочки приложения .

  • навигацияFallbackAllowlist

    RegExp[] необязательно

    Необязательный массив регулярных выражений, ограничивающий URL-адреса, к которым применяется настроенное поведение navigateFallback . Это полезно, если только часть URL-адресов вашего сайта следует рассматривать как часть одностраничного приложения . Если настроены оба — navigateFallbackDenylist и navigateFallbackAllowlist , список запретов имеет приоритет.

    Примечание . Эти регулярные выражения можно оценивать по каждому целевому URL-адресу во время навигации. Избегайте использования сложных регулярных выражений , иначе ваши пользователи могут столкнуться с задержками при навигации по вашему сайту.

  • навигацияFallbackDenylist

    RegExp[] необязательно

    Необязательный массив регулярных выражений, ограничивающий URL-адреса, к которым применяется настроенное поведение navigateFallback . Это полезно, если только часть URL-адресов вашего сайта следует рассматривать как часть одностраничного приложения . Если настроены оба navigateFallbackDenylist и navigateFallbackAllowlist , список запретов имеет приоритет.

    Примечание . Эти регулярные выражения можно оценивать по каждому целевому URL-адресу во время навигации. Избегайте использования сложных регулярных выражений , иначе ваши пользователи могут столкнуться с задержками при навигации по вашему сайту.

  • навигацияПредварительная загрузка

    логическое значение необязательно

    Значение по умолчанию: ложь.

    Включить или нет предварительную загрузку навигации в сгенерированном сервисном работнике. Если установлено значение true, вы также должны использовать runtimeCaching для настройки соответствующей стратегии ответа, которая будет соответствовать запросам навигации, и использовать предварительно загруженный ответ.

  • оффлайнGoogle Analytics

    логическое | GoogleAnalyticsInitializeOptions необязательно.

    Значение по умолчанию: ложь.

    Определяет, включать ли поддержку автономного Google Analytics . Если true , вызов initialize() workbox-google-analytics будет добавлен к созданному сервисному работнику. Если установлено значение Object , этот объект будет передан в вызов initialize() , что позволит вам настроить поведение.

  • Кэширование во время выполнения

    RuntimeCaching [] необязательно

    При использовании инструментов сборки Workbox для создания сервис-воркера вы можете указать одну или несколько конфигураций кэширования во время выполнения. Затем они преобразуются в вызовы workbox-routing.registerRoute с использованием заданной вами конфигурации соответствия и обработчика.

    Все параметры см. в документации workbox-build.RuntimeCaching . В приведенном ниже примере показана типичная конфигурация с двумя определенными маршрутами времени выполнения:

  • пропуститьОжидание

    логическое значение необязательно

    Значение по умолчанию: ложь.

    Добавлять ли безусловный вызов skipWaiting() к сгенерированному сервисному работнику. Если false , то вместо этого будет добавлен прослушиватель message , позволяющий клиентским страницам запускать skipWaiting() путем вызова postMessage({type: 'SKIP_WAITING'}) для ожидающего сервисного работника.

  • исходная карта

    логическое значение необязательно

    Значение по умолчанию: true

    Создавать ли исходную карту для созданных файлов сервис-воркера.

  • swDest

    строка необязательна

    Значение по умолчанию: «service-worker.js».

    Имя ресурса файла сервисного работника, созданного этим плагином.

InjectManifest

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

Используйте экземпляр InjectManifest в массиве plugins конфигурации веб-пакета.

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

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

Характеристики

Характеристики

default

Тип

объект

Характеристики

  • СоздатьSW

    запрос

  • Инжектманифест

    запрос