Настройка webpack-плагина: параметры и опции

Библиотека sw-precache предоставляет инструменты для автоматической генерации service worker с предзагрузкой (precache) статических ресурсов. В контексте сборщика webpack она используется через специализированные плагины, которые встраиваются в процесс сборки и формируют файл service worker на основе текущего состояния бандла.

Интеграция происходит на этапе завершения сборки, когда webpack уже сформировал список всех ассетов (JS, CSS, изображения и др.). Плагин анализирует этот список и генерирует service worker с заранее заданной стратегией кэширования.

Основные плагины для работы с sw-precache

Для webpack чаще всего применяются:

  • sw-precache-webpack-plugin — классический инструмент интеграции
  • кастомные скрипты генерации через API sw-precache

Пример подключения:

const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');

module.exports = {
  plugins: [
    new SWPrecacheWebpackPlugin({
      cacheId: 'my-app',
      filename: 'service-worker.js',
      staticFileGlobs: ['dist/**/*.{js,css,html,png,jpg}']
    })
  ]
};

Ключевые параметры конфигурации

cacheId

cacheId: 'my-app'

Уникальный идентификатор кэша. Используется для предотвращения конфликтов между различными приложениями на одном домене.

Особенности:

  • добавляется как префикс к имени кэша
  • влияет на стратегию обновления

filename

filename: 'service-worker.js'

Имя выходного файла service worker.

Важно:

  • должен располагаться в корне раздачи (обычно /dist)
  • влияет на область действия service worker (scope)

staticFileGlobs

staticFileGlobs: [
  'dist/**/*.js',
  'dist/**/*.css',
  'dist/**/*.html'
]

Список файлов для предварительного кэширования.

Особенности:

  • поддерживает glob-шаблоны
  • применяется до этапа хеширования
  • должен соответствовать реальной структуре файлов после сборки

stripPrefix

stripPrefix: 'dist/'

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

Пример:

dist/js/app.js → /js/app.js

Используется для корректной работы путей в браузере.

staticFileGlobsIgnorePatterns

staticFileGlobsIgnorePatterns: [
  /\.map$/,
  /asset-manifest\.json$/
]

Исключает файлы из precache.

Часто исключаются:

  • sourcemaps
  • временные файлы
  • служебные JSON

Настройки кэширования

maximumFileSizeToCacheInBytes

maximumFileSizeToCacheInBytes: 4194304 // 4MB

Ограничение размера файлов для кэширования.

Причины использования:

  • предотвращение переполнения cache storage
  • оптимизация загрузки

dontCacheBustUrlsMatching

dontCacheBustUrlsMatching: /\.\w{8}\./

Отключает добавление cache-busting параметров для файлов с хешами.

Пример:

app.12345678.js

Преимущества:

  • уменьшение размера service worker
  • более стабильный кэш

minify

minify: true

Минификация сгенерированного service worker.

Влияние:

  • уменьшает размер файла
  • ускоряет загрузку

runtimeCaching: динамическое кэширование

runtimeCaching: [
  {
    urlPattern: /\/api\//,
    handler: 'networkFirst'
  },
  {
    urlPattern: /\.(png|jpg|jpeg|svg)/,
    handler: 'cacheFirst'
  }
]

Позволяет задавать стратегии кэширования для ресурсов, не включённых в precache.

Основные стратегии:

  • cacheFirst

    • сначала кэш, затем сеть
    • подходит для изображений

  • networkFirst

    • сначала сеть, затем кэш
    • подходит для API

  • fastest

    • возвращает первый ответ (кэш или сеть)
navigateFallback: '/index.html'

Используется для SPA (Single Page Applications).

Поведение:

  • при переходе на неизвестный маршрут возвращается index.html
  • обеспечивает работу клиентского роутинга
navigateFallbackWhitelist: [
  /^\/(?!api).*$/
]

Ограничивает, для каких URL применяется fallback.

Пример:

  • применяется ко всем маршрутам, кроме /api

importScripts

importScripts: [
  '/sw-custom.js'
]

Позволяет подключать дополнительные скрипты в service worker.

Используется для:

  • кастомной логики
  • аналитики
  • расширенных стратегий кэширования

ignoreUrlParametersMatching

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

Игнорирует параметры URL при поиске в кэше.

Пример:

/index.html?utm_source=google

Будет сопоставлен с:

/index.html

handleFetch

handleFetch: true

Включает обработку fetch-запросов.

Если отключено:

  • service worker только предкэширует
  • не вмешивается в сетевые запросы

logger

logger: console

Позволяет кастомизировать логирование.

Используется для:

  • отладки
  • анализа поведения service worker

verbose

verbose: true

Включает подробный вывод логов.

Полезно при:

  • разработке
  • диагностике ошибок кэширования

sourcemap

sourcemap: false

Генерация source map для service worker.

Обычно отключается:

  • уменьшает размер
  • повышает безопасность

Пример полной конфигурации

new SWPrecacheWebpackPlugin({
  cacheId: 'advanced-app',
  filename: 'service-worker.js',
  staticFileGlobs: ['dist/**/*.{js,css,html,png,jpg}'],
  stripPrefix: 'dist/',
  staticFileGlobsIgnorePatterns: [/\.map$/, /manifest\.json$/],
  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
  dontCacheBustUrlsMatching: /\.\w{8}\./,
  minify: true,
  runtimeCaching: [
    {
      urlPattern: /\/api\//,
      handler: 'networkFirst'
    },
    {
      urlPattern: /\.(png|jpg|jpeg|svg)/,
      handler: 'cacheFirst'
    }
  ],
  navigateFallback: '/index.html',
  navigateFallbackWhitelist: [/^(?!\/api)/],
  ignoreUrlParametersMatching: [/^utm_/],
  handleFetch: true,
  verbose: false
})

Особенности взаимодействия с webpack

  1. Порядок плагинов

    • должен располагаться после генерации ассетов
    • влияет на корректность списка файлов

  2. Хеширование файлов

    • важно согласовать с dontCacheBustUrlsMatching
    • влияет на обновление кэша

  3. Output path

    • должен совпадать с staticFileGlobs
    • иначе файлы не попадут в precache

Типичные ошибки конфигурации

  • Несовпадение путей (dist/ vs /build/)
  • Отсутствие stripPrefix
  • Кэширование слишком больших файлов
  • Неправильные regex в runtimeCaching
  • Дублирование service worker

Оптимизация производительности

  • ограничение размера кэшируемых файлов
  • использование хешированных имён
  • минимизация service worker
  • исключение ненужных ассетов

Ограничения sw-precache

  • устаревание по сравнению с современными решениями (например, Workbox)
  • ограниченная гибкость runtime caching
  • сложность настройки сложных сценариев

Расширение функциональности

Через importScripts можно:

  • подключить кастомные стратегии
  • реализовать fallback-страницы
  • добавить offline-аналитику
  • внедрить push-уведомления

Связь с жизненным циклом service worker

Параметры webpack-плагина напрямую влияют на:

  • install — precache файлов
  • activate — очистка старых кэшей
  • fetch — обработка запросов

Корректная конфигурация обеспечивает:

  • мгновенную загрузку
  • offline-режим
  • предсказуемое обновление ресурсов
Оглавление