workbox-build: режим injectManifest

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

Основы режима injectManifest

В режиме injectManifest разработчик создаёт собственный файл сервис-воркера, в котором можно полностью контролировать логику кэширования, маршрутизацию и стратегию обновления. workbox-build анализирует этот файл и вставляет автоматически сгенерированный список ресурсов для кэширования в переменную self.__WB_MANIFEST.

Структура процесса:

  1. Создаётся исходный сервис-воркер sw.js или любой другой файл.
  2. В нём добавляется место для манифеста:
import { precacheAndRoute } from 'workbox-precaching';

precacheAndRoute(self.__WB_MANIFEST);
  1. В скрипте сборки вызывается workbox-build.injectManifest, который принимает исходный файл сервис-воркера, путь для финального сервиса и параметры кэширования.

Конфигурация injectManifest

Функция injectManifest принимает объект с обязательными и дополнительными параметрами:

  • swSrc (обязательный) – путь к исходному сервис-воркеру.
  • swDest (обязательный) – путь к итоговому сервис-воркеру после вставки манифеста.
  • globDirectory – корневая директория, откуда будут собираться файлы для кэширования.
  • globPatterns – массив шаблонов файлов для кэширования, например ['**/*.{js,css,html,png}'].
  • globIgnores – исключения, чтобы не включать файлы в манифест.
  • maximumFileSizeToCacheInBytes – лимит размера файлов для кэширования.

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

const { injectManifest } = require('workbox-build');

injectManifest({
  swSrc: 'src/sw.js',
  swDest: 'dist/sw.js',
  globDirectory: 'dist',
  globPatterns: ['**/*.{js,css,html,png,svg}'],
  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024, // 5 MB
}).then(({ count, size, warnings }) => {
  warnings.forEach(console.warn);
  console.log(`Сгенерировано ${count} файлов, общий размер: ${size} байт`);
});

Принципы работы с self.__WB_MANIFEST

self.__WB_MANIFEST — это массив объектов с информацией о ресурсах для предзагрузки. Каждый объект содержит:

  • url – относительный путь файла.
  • revision – хэш содержимого файла, используемый для контроля версий.

Пример после вставки манифеста:

self.__WB_MANIFEST = [
  { url: 'index.html', revision: '3a1f7b' },
  { url: 'main.js', revision: '9c2d4f' },
  { url: 'style.css', revision: '7f4b12' },
];

Использование precacheAndRoute(self.__WB_MANIFEST) автоматически добавляет все эти ресурсы в кэш при установке сервис-воркера.

Расширенные возможности

1. Собственные стратегии кэширования

Режим injectManifest не ограничивает разработчика предзагрузкой. Можно добавлять маршруты с различными стратегиями Workbox:

import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate } from 'workbox-strategies';

registerRoute(
  ({ request }) => request.destination === 'image',
  new StaleWhileRevalidate({
    cacheName: 'images-cache',
    plugins: [
      {
        cacheWillUpdate: async ({ response }) => {
          if (response.status === 200) return response;
          return null;
        }
      }
    ]
  })
);
2. Интеграция с динамическим контентом

Можно создавать динамические кэши для API-запросов:

registerRoute(
  ({ url }) => url.origin === 'https://api.example.com',
  new StaleWhileRevalidate({ cacheName: 'api-cache' })
);
3. Контроль версий кэша

Присваивание уникального cacheName и использование revision в __WB_MANIFEST позволяют эффективно управлять обновлениями ресурсов и избегать устаревшего контента.

Преимущества подхода injectManifest

  • Полный контроль над логикой сервис-воркера.
  • Возможность интеграции любых стратегий кэширования и маршрутизации.
  • Безопасное автоматическое включение всех статических ресурсов проекта с хешированием.
  • Совместимость с современными сборщиками (Webpack, Rollup, Vite).

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

  • Всегда использовать уникальные revision для файлов, чтобы изменения корректно отражались в кэше.
  • Ограничивать maximumFileSizeToCacheInBytes для крупных ресурсов, чтобы избежать переполнения кэша.
  • Регулярно проверять warnings после генерации манифеста, чтобы исключить невалидные файлы.
  • В production-сборке использовать минифицированные ресурсы для уменьшения объёма кэша.

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

Оглавление