Сервис-воркеры в виде ES-модулей
Переведите service worker на ES-модуль: статические импорты, общий код, сборка, кэширование обновлений и резервный вариант для старых браузеров.
Чтобы запустить сервис-воркер как ES-модуль, вызовите navigator.serviceWorker.register('/sw.js', { type: 'module' }). Без этой опции браузер загружает файл как классический скрипт, и import и export вызывают синтаксическую ошибку.
Большинство команд приходят к этому одинаково. Приложение целиком написано на ESM и собирается Vite, а сервис-воркер по-прежнему остаётся классическим скриптом, который через importScripts() подключает вручную скопированный конфигурационный файл, постепенно расходящийся с приложением. Перевод воркера на модули решает эту проблему, но модульные воркеры подчиняются другим правилам, а полная поддержка в браузерах появилась только с выходом Firefox 147. В статье рассматриваются изменения при регистрации, общий код для страницы и воркера, правила, из-за которых ломаются модульные воркеры, поведение обновлений, результат сборки и запасной вариант. Основы жизненного цикла описаны в статье A Practical Guide to Service Workers.
Ключевые выводы
- Передача
{ type: 'module' }вregister()превращает сервис-воркер в ES-модуль. Тип по умолчанию —'classic'. - Вызов
importScripts()в модульном воркере выбрасываетTypeError, поэтому каждый такой вызов нужно заменить статическимimport. - Динамический
import()и карты импорта (import maps) в сервис-воркерах не работают, поэтому каждый спецификатор должен разрешаться в реальный URL на этапе сборки. - Модульные сервис-воркеры поддерживаются в Chrome и Edge 91+, Safari 15+ и Firefox 147+.
- Настройка по умолчанию
updateViaCache: 'imports'позволяет при проверке обновлений брать импортируемые модули из HTTP-кеша, поэтому общим модулям стоит давать URL с хешем или короткое время кеширования.
Как перевести сервис-воркер на ES-модули?
Для этого нужны два изменения: передать опцию type при регистрации и заменить importScripts() на import. Согласно справочнику MDN по register(), type принимает значения 'classic' (по умолчанию) или 'module'.
Классический вариант:
// config.js (classic)
self.CACHE_NAME = 'app-v3';
// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);
Модульный вариант:
// config.js (module)
export const CACHE_NAME = 'app-v3';
// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);
Модульные скрипты загружаются с использованием CORS, выполняются в строгом режиме (strict mode) и должны отдаваться с JavaScript MIME-типом, например text/javascript, — как поясняется для модульных воркеров на странице MDN о конструкторе Worker().
Общий код для страницы и воркера
Главная причина писать сервис-воркер в виде ES-модуля — один и тот же модуль может обслуживать и страницу, и воркер. Вынесите имя кеша и список URL для предварительного кеширования в один файл:
// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];
Воркер импортирует оба значения и использует стандартные вызовы Cache API:
// sw.js
import { CACHE_NAME, PRECACHE_URLS } from './config.js';
self.addEventListener('install', (event) => {
event.waitUntil(
caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
);
});
self.addEventListener('activate', (event) => {
event.waitUntil(
caches.keys().then((keys) =>
Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
)
);
});
Страница импортирует тот же файл:
// main.js, loaded via <script type="module">
import { CACHE_NAME } from './config.js';
console.debug('Expected cache:', CACHE_NAME);
navigator.serviceWorker.register('/sw.js', { type: 'module' });
Теперь строку версии достаточно изменить в одном месте, и изменение увидят обе стороны.
Три правила, из-за которых ломаются модульные сервис-воркеры
Большинство сбоев при переводе классического сервис-воркера на ES-модули связано с тремя правилами.
- Никакого
importScripts(). Согласно алгоритмуimportScripts()в спецификации HTML, если тип глобальной области видимости —"module", выбрасываетсяTypeError, а справочник MDN поimportScripts()рекомендует модульным воркерам использоватьimport. Если воркер загружает библиотеку черезimportScripts(), вам понадобится её ESM-сборка. - Никакого динамического
import(). На странице MDN оServiceWorkerуказано, что спецификация запрещает динамическийimport()в сервис-воркерах и его вызов приводит к исключению. Любой код, который нужен по условию, загружайте заранее статическим импортом. - Никаких карт импорта. Import maps внутри сервис-воркеров не действуют, а их поддержка в воркерах пока остаётся открытым предложением (whatwg/html #8173). Каждый спецификатор должен быть относительным или абсолютным URL. «Голое» имя вроде
'idb'не разрешится как спецификатор модуля, поэтому на этапе сборки его нужно переписать или встроить.
Как импортируемые модули влияют на обновление сервис-воркера
В модульном сервис-воркере импортируемые модули участвуют в проверке обновлений. Изменение статически импортируемого файла, например config.js, может запустить процесс обновления, даже если сам sw.js не менялся, — точно так же, как обрабатываются зависимости importScripts(). Об этом говорится в анонсе модульных сервис-воркеров от Chrome.
Опция updateViaCache определяет, может ли такая проверка использовать HTTP-кеш:
| Значение | Основной скрипт | Импортируемые модули |
|---|---|---|
'imports' (по умолчанию) | Всегда из сети | Допускается HTTP-кеш |
'all' | Допускается HTTP-кеш | Допускается HTTP-кеш |
'none' | Всегда из сети | Всегда из сети |
При значении по умолчанию общий модуль, отдаваемый по URL без хеша с большим max-age, может оставаться устаревшим при проверках обновлений. Можно отдавать общие модули по URL с хешем содержимого, задать им короткое время кеширования или регистрировать воркер с updateViaCache: 'none'. Записи сессий, в которых пользователи после деплоя продолжают видеть старый интерфейс или запрашивают хешированные ресурсы, которых уже не существует, часто указывают именно на такую ошибку обновления. Как убедиться, какая версия воркера сейчас управляет страницей, рассказывается в статье о отладке сервис-воркеров.
Инструменты сборки: ESM без бандлинга или единый файл
Vite обрабатывает сервис-воркер как любой другой выходной файл: его нужно сгенерировать как отдельную точку входа со стабильным URL без хеша, например /sw.js. Если URL меняется при каждой сборке, регистрация каждый раз указывает на другой скрипт. Каталог public в Vite копирует файлы без обработки — это подходит для написанного вручную воркера, но его импорты при этом не разрешаются.
Собрать модульный сервис-воркер можно одним из двух способов:
- ESM без бандлинга.
sw.jsи общие модули поставляются отдельными файлами со спецификаторами в виде URL, а регистрация выполняется сtype: 'module'. Каждый импорт загружается отдельным запросом и учитывается при проверке обновлений. - Единый собранный файл. Бандлер встраивает всё, включая пакеты с «голыми» спецификаторами, в один скрипт. Если в результате нет инструкций
import, такой файл работает и как классический воркер — это и будет ваш запасной вариант.
Запасной вариант для браузеров без поддержки модулей
Все четыре основных движка поддерживают модульные сервис-воркеры, согласно данным MDN browser-compat-data на caniuse:
| Браузер | Первая версия с поддержкой type: 'module' |
|---|---|
| Chrome | 91 |
| Edge | 91 |
| Safari (macOS и iOS) | 15 |
| Firefox | 147, согласно примечаниям к выпуску Firefox 147 |
Классическая сборка нужна только для старых браузеров: Chrome и Edge 90 и ниже, Safari 14.1 и ниже, Firefox 146 и ниже. Стандартного API для определения поддержки модулей нет, о чём свидетельствует запрос на feature detection в w3c/ServiceWorker #1582. Старый браузер не отклоняет опцию type сразу: он загружает скрипт, не может его выполнить, и register() завершается с ошибкой. Это отклонение можно перехватить:
async function registerSW() {
if (!('serviceWorker' in navigator)) return;
try {
return await navigator.serviceWorker.register('/sw.js', { type: 'module' });
} catch (err) {
console.warn('Module service worker failed, falling back to classic:', err);
return navigator.serviceWorker.register('/sw-classic.js');
}
}
У такого запасного варианта на try/catch есть два недостатка. Старые браузеры впустую загружают модульный скрипт. Кроме того, catch скрывает и реальные ошибки модульного воркера в поддерживающих браузерах, поэтому логируйте ошибку перед переключением на классическую версию.
Заключение
Перевод сервис-воркера на модули сводится к опции type и трём правилам: только статические импорты, никакого importScripts() и никаких «голых» спецификаторов. Для начала вынесите константы, которые дублируются в воркере и на странице, в один общий модуль, регистрируйте воркер с { type: 'module' } и проверьте, как кешируется этот модуль, чтобы его изменения доходили до пользователей через проверку обновлений.
Часто задаваемые вопросы
Можно ли использовать top-level await в модульном сервис-воркере?
Нет. Top-level await в сервис-воркерах запрещён, потому что начальное выполнение скрипта должно завершиться синхронно, чтобы обработчики событий, например install и fetch, успели зарегистрироваться. Chromium отклоняет такую регистрацию с ошибкой TypeError. Это касается и случаев, когда await находится в статически импортируемом модуле, поскольку он делает асинхронным весь граф модулей. Перенесите асинхронную инициализацию в обработчик install или activate, обернув её в event.waitUntil().
Запускает ли перевод существующего сервис-воркера с classic на module по тому же URL обновление?
Да. Спецификация Service Workers считает изменение типа воркера обновлением, даже если URL скрипта и его содержимое не изменились. Вызов register('/sw.js', { type: 'module' }) поверх существующей классической регистрации устанавливает новый воркер, который затем проходит обычный жизненный цикл ожидания и активации. Вызов register() с тем же URL, типом и значением updateViaCache завершается успешно без каких-либо загрузок.
Может ли модульный сервис-воркер импортировать модули с CDN или другого источника?
Да, если другой источник это разрешает. Модули импортируются с использованием CORS, поэтому модуль с другого источника должен отдаваться с заголовком Access-Control-Allow-Origin, разрешающим ваш источник. Иначе импорт завершится ошибкой, и register() будет отклонён. Классическим вызовам importScripts() это не требуется, поскольку они загружают скрипты в режиме no-cors. Сам скрипт сервис-воркера при этом по-прежнему должен находиться в том же источнике, что и регистрирующая его страница.