workbox-build: режим getManifest

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

Основные принципы работы режима getManifest

Метод getManifest используется для анализа указанной директории и создания массива объектов, каждый из которых описывает ресурс, его путь и хеш-сумму содержимого. Этот массив затем может быть передан в сервис-воркер для precache.

Пример базового вызова:

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

async function buildManifest() {
  const manifest = await getManifest({
    globDirectory: 'dist/',
    globPatterns: [
      '**/*.{js,css,html,png,jpg,json}'
    ]
  });

  console.log(manifest);
}

buildManifest();

Ключевые параметры:

  • globDirectory – корневая директория проекта, где располагаются статические файлы.
  • globPatterns – массив шаблонов, определяющих, какие файлы включать в precache.
  • globIgnores – массив шаблонов для исключения файлов (например, ['**/ignored.js']).
  • dontCacheBustURLsMatching – регулярное выражение для файлов, хеш которых уже встроен в имя. Позволяет избежать лишней генерации хеша.
  • maximumFileSizeToCacheInBytes – ограничение на размер файла для precache, чтобы не включать очень большие ресурсы.

Метод возвращает объект с ключами:

  • count – количество файлов, найденных для precache.
  • size – общий размер файлов в байтах.
  • manifest – массив объектов вида:
{
  url: 'main.abcdef.js',
  revision: '1234567890abcdef'
}

Интеграция с кастомным сервис-воркером

Режим getManifest позволяет гибко интегрировать precache в уже существующие сервис-воркеры. Пример:

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

async function injectPrecache() {
  const { manifest } = await getManifest({
    globDirectory: 'dist/',
    globPatterns: ['**/*.js', '**/*.css', '**/*.html']
  });

  const swTemplate = `
    import { precacheAndRoute } from 'workbox-precaching';

    precacheAndRoute(${JSON.stringify(manifest)});
    
    self.addEventListener('fetch', (event) => {
      // дополнительные стратегии кеширования
    });
  `;

  fs.writeFileSync('dist/sw.js', swTemplate);
}

injectPrecache();

В этом примере:

  • Генерируется список ресурсов с getManifest.
  • Формируется сервис-воркер, где ресурсы передаются в precacheAndRoute.
  • Позволяет добавлять пользовательские обработчики событий fetch или других событий сервис-воркера.

Управление версиями и ревизиями

Каждый объект манифеста содержит поле revision, которое автоматически создается на основе хеша содержимого файла. Это обеспечивает:

  • Автоматическое обновление кеша при изменении файлов.
  • Исключение из precache старых версий ресурсов.
  • Оптимизацию загрузки за счет точного контроля ревизий.

Если необходимо вручную управлять ревизиями, можно модифицировать массив manifest после вызова getManifest, перед передачей его в precacheAndRoute.

Использование dontCacheBustURLsMatching

Этот параметр позволяет исключить из пересчета хеша файлы, уже содержащие уникальный идентификатор в имени. Например, если сборка использует хеширование в имени main.abcdef.js, можно задать:

dontCacheBustURLsMatching: /\.[0-9a-f]{8}\./

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

Ограничение размера файлов

Чтобы избежать кеширования слишком больших ресурсов (например, видео или больших JSON), используется параметр maximumFileSizeToCacheInBytes:

maximumFileSizeToCacheInBytes: 5 * 1024 * 1024 // 5MB

Файлы, превышающие этот размер, будут проигнорированы при генерации манифеста.

Применение в сложных сборках

Режим getManifest идеально подходит для:

  • Систем, где сервис-воркер собирается через Webpack, Rollup или другие инструменты.
  • Проектов с динамическим формированием списка ресурсов, когда precache нужен до генерации основного воркера.
  • Интеграции с CI/CD, где необходимо получать список актуальных ресурсов и автоматически подставлять их в шаблон сервис-воркера.
Оглавление