12k
All articles

Service Worker als ES-Module schreiben

Stellen Sie einen Service Worker auf ein ES-Modul um: mit statischen Imports, gemeinsamem Code, Build-Optionen, Update-Caching und Fallback für ältere Browser.

OpenReplay Team
OpenReplay Team
Service Worker als ES-Module schreiben

Um einen Service Worker als ES-Modul auszuführen, rufen Sie navigator.serviceWorker.register('/sw.js', { type: 'module' }) auf. Ohne diese Option lädt der Browser die Datei als klassisches Skript, sodass import und export zu Syntaxfehlern führen.

Die meisten Teams landen auf dieselbe Weise an diesem Punkt. Die App ist durchgehend ESM und wird mit Vite gebaut, doch der Service Worker ist noch ein klassisches Skript. Er lädt per importScripts() eine von Hand kopierte Konfigurationsdatei, die mit der Zeit von der App abweicht. Die Umstellung des Workers auf ein Modul löst dieses Problem. Allerdings gelten für Modul-Worker andere Regeln, und die Browserunterstützung ist erst seit Firefox 147 vollständig. Dieser Artikel behandelt die Änderung bei der Registrierung, die gemeinsame Nutzung von Code mit der Seite, die Regeln, an denen Modul-Worker scheitern, das Update-Verhalten, die Build-Ausgabe und einen Fallback. Grundlagen zum Lebenszyklus finden Sie in A Practical Guide to Service Workers.

Das Wichtigste in Kürze

  • Wenn Sie { type: 'module' } an register() übergeben, wird der Service Worker zum ES-Modul. Der Standardtyp ist 'classic'.
  • Ein Aufruf von importScripts() in einem Modul-Worker wirft einen TypeError. Deshalb muss jeder Aufruf durch ein statisches import ersetzt werden.
  • Dynamisches import() und Import Maps funktionieren in Service Workern nicht. Jeder Specifier muss daher zur Build-Zeit auf eine echte URL auflösen.
  • Modul-Service-Worker funktionieren in Chrome und Edge ab Version 91, in Safari ab Version 15 und in Firefox ab Version 147.
  • Bei der Standardeinstellung updateViaCache: 'imports' dürfen Update-Prüfungen importierte Module aus dem HTTP-Cache laden. Versehen Sie gemeinsam genutzte Module deshalb mit gehashten URLs oder kurzen Cache-Laufzeiten.

Wie stellt man einen Service Worker auf ein ES-Modul um?

Für die Umstellung eines Service Workers auf ein ES-Modul sind zwei Änderungen nötig. Sie übergeben bei der Registrierung die Option type und ersetzen importScripts() durch import. Laut der MDN-Referenz zu register() akzeptiert type die Werte 'classic' (Standard) oder 'module'.

Hier die klassische Variante:

// config.js (classic)
self.CACHE_NAME = 'app-v3';

// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);

Und die Modul-Variante:

// config.js (module)
export const CACHE_NAME = 'app-v3';

// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);

Modulskripte werden per CORS geladen und laufen im Strict Mode. Außerdem müssen sie mit einem JavaScript-MIME-Typ wie text/javascript ausgeliefert werden. Das erläutert die MDN-Seite zum Worker()-Konstruktor für Modul-Worker.

Code zwischen Seite und Worker teilen

Der wichtigste Grund, einen Service Worker als ES-Modul zu schreiben: Ein einziges Modul kann sowohl die Seite als auch den Worker bedienen. Legen Sie den Cache-Namen und die Precache-Liste in einer gemeinsamen Datei ab:

// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];

Der Worker importiert beide Werte und nutzt die üblichen Aufrufe der 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)))
    )
  );
});

Die Seite importiert dieselbe Datei:

// 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' });

Sie erhöhen den Versionsstring jetzt an einer einzigen Stelle, und beide Seiten übernehmen die Änderung.

Drei Regeln, an denen Modul-Service-Worker scheitern

Bei der Umstellung eines klassischen Service Workers auf ein ES-Modul gehen die meisten Fehler auf drei Regeln zurück.

  1. Kein importScripts(). Gemäß den Verarbeitungsschritten für importScripts() in der HTML-Spezifikation wird ein TypeError geworfen, wenn der Typ des globalen Scopes "module" ist. Die MDN-Referenz zu importScripts() verweist Modul-Worker stattdessen auf import. Wenn Ihr Worker eine Bibliothek über importScripts() lädt, benötigen Sie einen ESM-Build dieser Bibliothek.
  2. Kein dynamisches import(). Laut der MDN-Seite zu ServiceWorker verbietet die Spezifikation dynamisches import() in Service Workern, und ein entsprechender Aufruf wirft einen Fehler. Laden Sie Code, den Sie nur unter bestimmten Bedingungen benötigen, deshalb vorab per statischem Import.
  3. Keine Import Maps. Import Maps gelten innerhalb von Service Workern nicht. Ihre Unterstützung in Workern ist noch ein offener Vorschlag (whatwg/html #8173). Jeder Specifier muss eine relative oder absolute URL sein. Ein Bare Specifier wie 'idb' lässt sich nicht als Modul-Specifier auflösen. Ein Build-Schritt muss ihn daher umschreiben oder inlinen.

Wie importierte Module Service-Worker-Updates beeinflussen

In einem Modul-Service-Worker sind importierte Module Teil der Update-Prüfung. Eine Änderung an einer statisch importierten Datei wie config.js kann den Update-Vorgang auslösen, auch wenn sich sw.js nicht geändert hat. Abhängigkeiten über importScripts() werden genauso behandelt, wie Chromes Ankündigung der Modul-Service-Worker festhält.

Die Option updateViaCache legt fest, ob diese Prüfungen den HTTP-Cache verwenden dürfen:

WertHauptskriptImportierte Module
'imports' (Standard)Immer aus dem NetzwerkHTTP-Cache erlaubt
'all'HTTP-Cache erlaubtHTTP-Cache erlaubt
'none'Immer aus dem NetzwerkImmer aus dem Netzwerk

Mit der Standardeinstellung kann ein gemeinsam genutztes Modul trotz Update-Prüfungen veraltet bleiben. Das passiert, wenn es unter einer URL ohne Hash und mit langem max-age ausgeliefert wird. Als Gegenmaßnahme können Sie gemeinsam genutzte Module unter URLs mit Content-Hash ausliefern, ihnen kurze Cache-Laufzeiten geben oder mit updateViaCache: 'none' registrieren. Session Replays zeigen nach einem Deployment oft Nutzer, die noch die alte Oberfläche sehen oder gehashte Assets anfordern, die nicht mehr existieren. Solche Fälle deuten häufig auf genau diese Art von Update-Fehler hin. Wie Sie prüfen, welche Worker-Version die Kontrolle hat, erfahren Sie unter Debugging von Service Workern.

Build-Tools: ungebündeltes ESM oder eine einzelne Datei

Vite behandelt einen Service Worker wie jede andere Ausgabedatei. Er muss als eigener Einstiegspunkt unter einer stabilen URL ohne Hash wie /sw.js ausgegeben werden. Ändert sich die URL bei jedem Build, verweist die Registrierung jedes Mal auf ein anderes Skript. Vites public-Verzeichnis kopiert Dateien unverarbeitet. Das eignet sich für einen handgeschriebenen Worker, löst aber dessen Imports nicht auf.

Für den Build eines Modul-Service-Workers gibt es zwei Wege:

  • Ungebündeltes ESM. sw.js und die gemeinsam genutzten Module werden als separate Dateien mit URL-Specifiern ausgeliefert, und die Registrierung erfolgt mit type: 'module'. Jeder Import ist ein eigener Fetch und wird von der Update-Prüfung erfasst.
  • Eine einzelne gebündelte Datei. Der Bundler fügt alles in ein Skript ein, auch Pakete mit Bare Specifiern. Enthält die Ausgabe keine import-Anweisungen, läuft sie auch als klassischer Worker und dient damit als Fallback.

Fallback für Browser ohne Modulunterstützung

Laut den MDN-Browser-Compat-Daten auf caniuse unterstützen alle vier großen Engines Modul-Service-Worker:

BrowserErste Version mit type: 'module'
Chrome91
Edge91
Safari (macOS und iOS)15
Firefox147, laut den Release Notes zu Firefox 147

Einen klassischen Build benötigen Sie nur für ältere Browser, also für Chrome und Edge bis Version 90, Safari bis 14.1 und Firefox bis 146. Eine Standard-API zur Erkennung der Modulunterstützung gibt es nicht, wie die Anfrage zur Feature Detection in w3c/ServiceWorker #1582 zeigt. Ein älterer Browser lehnt die Option type nicht von vornherein ab. Er lädt das Skript herunter, kann es nicht auswerten, und register() wird mit einem Fehler abgelehnt. Diesen Fehler können Sie abfangen:

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');
  }
}

Dieser try/catch-Fallback hat zwei Nachteile. Ältere Browser laden das Modulskript umsonst herunter. Zudem verdeckt der catch-Block in unterstützten Browsern auch echte Fehler im Modul-Worker. Protokollieren Sie den Fehler daher, bevor Sie auf den Fallback ausweichen.

Fazit

Die Umstellung eines Service Workers auf ein Modul läuft auf die Option type und drei Regeln hinaus: nur statische Imports, kein importScripts() und keine Bare Specifier. Verschieben Sie zum Einstieg die Konstanten, die Worker und Seite doppelt pflegen, in ein gemeinsames Modul. Registrieren Sie den Worker anschließend mit { type: 'module' }. Prüfen Sie außerdem, wie dieses Modul gecacht wird, damit Änderungen daran die Nutzer über die Update-Prüfung erreichen.

FAQs

Kann ich Top-Level-Await in einem Modul-Service-Worker verwenden?

Nein. Top-Level-Await ist in Service Workern nicht erlaubt, weil die initiale Auswertung synchron abgeschlossen sein muss, damit Listener wie install und fetch rechtzeitig registriert werden. Chromium lehnt die Registrierung mit einem TypeError ab. Das gilt auch, wenn das await in einem statisch importierten Modul steht, denn dadurch wird der gesamte Modulgraph asynchron. Verlagern Sie asynchrone Initialisierung in einen install- oder activate-Handler, umschlossen von event.waitUntil().

Löst die Umstellung eines bestehenden Service Workers von classic auf module unter derselben URL ein Update aus?

Ja. Die Service-Workers-Spezifikation behandelt eine Änderung des Worker-Typs als Update, selbst wenn Skript-URL und Inhalt identisch sind. Ein Aufruf von register('/sw.js', { type: 'module' }) über eine bestehende klassische Registrierung installiert einen neuen Worker, der anschließend den normalen Lebenszyklus aus Warten und Aktivierung durchläuft. Ein register()-Aufruf mit identischer URL, identischem type und identischem updateViaCache-Wert wird aufgelöst, ohne etwas abzurufen.

Kann ein Modul-Service-Worker Module von einem CDN oder einem anderen Origin importieren?

Ja, sofern der andere Origin das erlaubt. Modul-Imports werden per CORS abgerufen. Ein Cross-Origin-Modul muss daher mit einem Access-Control-Allow-Origin-Header ausgeliefert werden, der Ihren Origin zulässt. Andernfalls schlägt der Import fehl und register() wird abgelehnt. Klassische importScripts()-Aufrufe benötigen das nicht, da sie Skripte im no-cors-Modus laden. Das Service-Worker-Skript selbst muss weiterhin denselben Origin haben wie die Seite, die es registriert.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.