Установка через npm

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

1. Инициализация проекта

Перед установкой Workbox необходимо убедиться, что проект настроен как npm-пакет. Для этого выполняется команда:

npm init -y

Она создаёт файл package.json с базовыми настройками проекта, что позволяет управлять зависимостями, скриптами сборки и другими параметрами.

2. Установка Workbox

Workbox доступен как набор отдельных пакетов, каждый из которых отвечает за определённые функции:

  • workbox-core — базовые утилиты для работы с сервис-воркерами.
  • workbox-routing — маршрутизация запросов и управление стратегиями кэширования.
  • workbox-strategies — готовые стратегии кэширования, такие как NetworkFirst, CacheFirst, StaleWhileRevalidate.
  • workbox-precaching — предварительное кэширование ресурсов при установке сервис-воркера.
  • workbox-build — генерация манифестов для кэширования и интеграция с системой сборки.
  • workbox-webpack-plugin — плагин для Webpack, автоматизирующий работу с precaching.

Установка всех основных пакетов производится командой:

npm install workbox-core workbox-routing workbox-strategies workbox-precaching workbox-build workbox-webpack-plugin --save

Флаг --save добавляет пакеты в список зависимостей проекта.

3. Структура проекта после установки

После установки Workbox структура проекта может выглядеть следующим образом:

project/
├─ src/
│  ├─ index.js
│  └─ service-worker.js
├─ package.json
├─ package-lock.json
└─ node_modules/
  • src/service-worker.js — основной файл сервис-воркера, где подключаются модули Workbox.
  • node_modules/ — каталог с установленными пакетами Workbox и их зависимостями.
  • package-lock.json — фиксирует точные версии всех установленных пакетов для воспроизводимой сборки.

4. Использование модулей Workbox в сервис-воркере

Импорт модулей Workbox в сервис-воркер осуществляется через синтаксис ES-модулей (если проект поддерживает модульную сборку) или через глобальный объект workbox при использовании CDN. В npm-проектах предпочтительно использовать ES-модули:

import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate } from 'workbox-strategies';
  • precacheAndRoute() автоматически кэширует ресурсы, перечисленные в манифесте.
  • registerRoute() позволяет определять маршруты для сетевых запросов и применять к ним стратегии кэширования.
  • StaleWhileRevalidate — стратегия, которая возвращает кэшированный ответ мгновенно и одновременно обновляет его из сети.

5. Интеграция с инструментами сборки

Для проектов на Webpack можно использовать workbox-webpack-plugin. Установка через npm уже рассмотрена, подключение плагина выглядит так:

const { GenerateSW } = require('workbox-webpack-plugin');

module.exports = {
  // остальная конфигурация Webpack
  plugins: [
    new GenerateSW({
      clientsClaim: true,
      skipWaiting: true,
      runtimeCaching: [
        {
          urlPattern: /\.(?:png|jpg|jpeg|svg|gif)$/,
          handler: 'CacheFirst',
          options: {
            cacheName: 'images-cache',
            expiration: {
              maxEntries: 50,
              maxAgeSeconds: 30 * 24 * 60 * 60 // 30 дней
            },
          },
        },
      ],
    }),
  ],
};

Плагин автоматически генерирует сервис-воркер, добавляет precaching для статических ресурсов и настраивает runtime caching для динамических запросов.

6. Проверка установки

После установки пакетов и настройки сервис-воркера можно проверить работу Workbox с помощью команд:

npx workbox-cli generateSW workbox-config.js

Или запустить проект через локальный сервер и убедиться, что сервис-воркер зарегистрирован и кэширование работает. В DevTools браузера во вкладке Application → Service Workers отображается активный сервис-воркер и список кэшированных ресурсов.

7. Обновление и управление зависимостями

Для обновления пакетов Workbox до последних стабильных версий используется:

npm update workbox-core workbox-routing workbox-strategies workbox-precaching workbox-build workbox-webpack-plugin

Файл package.json фиксирует версии, что позволяет сохранять совместимость при последующих сборках. Для управления точными версиями можно использовать символ ^ или ~ перед номером версии.

8. Особенности использования через npm

  • Полная интеграция с системами сборки позволяет автоматически генерировать манифесты для precaching.
  • Модули Workbox можно импортировать по отдельности, минимизируя размер бандла.
  • npm-подход обеспечивает контроль версий и совместимость с другими библиотеками проекта.
  • Совместим с TypeScript, если подключить соответствующие типы (@types/workbox-*), что позволяет использовать автодополнение и проверку типов при разработке.
Оглавление