Интеграция с Vite через vite-plugin-pwa

Для использования возможностей Workbox в проекте на Vite применяется плагин vite-plugin-pwa. Он обеспечивает генерацию сервис-воркера, управление кешированием и автоматическое создание манифеста Progressive Web App.

npm install vite-plugin-pwa --save-dev

В конфигурационном файле Vite (vite.config.js или vite.config.ts) необходимо импортировать плагин и настроить его:

import { defineConfig } from 'vite';
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'My App',
        short_name: 'App',
        start_url: '/',
        display: 'standalone',
        background_color: '#ffffff',
        theme_color: '#4DBA87',
        icons: [
          {
            src: 'icon-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: 'icon-512x512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      workbox: {
        runtimeCaching: [
          {
            urlPattern: /^https:\/\/cdn\.example\.com\/.*\.(js|css)$/,
            handler: 'CacheFirst',
            options: {
              cacheName: 'cdn-cache',
              expiration: {
                maxEntries: 50,
                maxAgeSeconds: 7 * 24 * 60 * 60
              }
            }
          },
          {
            urlPattern: /\/api\/.*$/,
            handler: 'NetworkFirst',
            options: {
              cacheName: 'api-cache',
              networkTimeoutSeconds: 5,
              expiration: {
                maxEntries: 30,
                maxAgeSeconds: 24 * 60 * 60
              }
            }
          }
        ],
        navigateFallback: '/index.html',
        globPatterns: ['**/*.{js,css,html,png,jpg,svg}'],
        globIgnores: ['**/node_modules/**']
      }
    })
  ]
});

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

Workbox предоставляет несколько стратегий кеширования:

  • CacheFirst: сначала проверяет кеш, затем сеть. Используется для статических ресурсов (CSS, JS, шрифты, изображения).
  • NetworkFirst: сначала делает запрос к сети, затем использует кеш при недоступности сети. Подходит для API-запросов.
  • StaleWhileRevalidate: возвращает кешированные данные мгновенно и обновляет их в фоне. Идеально для часто обновляемого контента.
  • NetworkOnly и CacheOnly: используются редко, только при специфических требованиях.

В vite-plugin-pwa эти стратегии настраиваются через массив runtimeCaching, где для каждой группы ресурсов указывается:

  • urlPattern — регулярное выражение для совпадения URL
  • handler — выбранная стратегия
  • options — дополнительные параметры: cacheName, expiration, cacheableResponse и т.д.

Интеграция с модульной системой Vite

Vite использует ES-модули, поэтому сервис-воркер создается с поддержкой ES. Плагин автоматически генерирует файл сервис-воркера (sw.js) в папке dist. При необходимости можно добавить собственный сервис-воркер с кастомными обработчиками событий:

// src/custom-sw.js
import { clientsClaim } from 'workbox-core';
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate } from 'workbox-strategies';

clientsClaim();

precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({ request }) => request.destination === 'image',
  new StaleWhileRevalidate({
    cacheName: 'images-cache',
  })
);

В конфигурации плагина подключение кастомного воркера происходит через опцию srcDir и filename:

VitePWA({
  srcDir: 'src',
  filename: 'custom-sw.js',
  strategies: 'injectManifest',
});

Автообновление сервис-воркера

Опция registerType: 'autoUpdate' обеспечивает автоматическую проверку нового воркера при загрузке страницы. При изменении ресурсов Workbox обновляет кеш без вмешательства пользователя. Для тонкой настройки можно использовать события Workbox:

navigator.serviceWorker.addEventListener('controllerchange', () => {
  console.log('Сервис-воркер обновлен');
});

Предварительное кеширование статических ресурсов

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

Оптимизация кеширования

  • Ограничение числа объектов в кеше через maxEntries.
  • Задание времени жизни через maxAgeSeconds.
  • Игнорирование определенных путей через globIgnores.
  • Разделение кешей по типам ресурсов для предотвращения переполнения одного кеша.

Отладка и тестирование

  • Использовать вкладку Application > Service Workers в DevTools.
  • Проверять содержимое кеша через Cache Storage.
  • Проверять работу стратегии NetworkFirst, отключая сеть в DevTools.
  • Включить логирование Workbox для детальной отладки:
import { setConfig } from 'workbox-core';
setConfig({ debug: true });

Итоговая структура проекта

project/
│
├─ src/
│   ├─ main.js
│   └─ custom-sw.js
│
├─ public/
│   └─ icons/
│
├─ vite.config.js
└─ package.json

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

Оглавление