ServiceWorkerContainer.register() — Methode · JavaScript-Referenz

Signatur

ServiceWorkerContainer.prototype.register(scriptURL, options)

Beschreibung

Mit navigator.serviceWorker.register() meldest du ein Service-Worker-Skript beim Browser an. Der Service Worker läuft danach unabhängig von der Seite im Hintergrund. Er kann Netzwerkanfragen abfangen (fetch-Event), Inhalte cachen und damit Offline-Betrieb ermöglichen. Außerdem ist er die Grundlage für Push-Benachrichtigungen und Background Sync. Er ist damit der Kern jeder Progressive Web App (PWA).

Der Scope legt fest, welche Seiten der Service Worker steuert. Standardmäßig ist das das Verzeichnis, in dem das Skript liegt: /js/sw.js steuert also nur /js/…. Einen engeren Scope kannst du über options.scope festlegen. Für einen weiteren Scope als den Skriptpfad muss der Server den HTTP-Header Service-Worker-Allowed senden. Deshalb liegt sw.js meist im Wurzelverzeichnis.

Gibt es für denselben Scope schon eine Registrierung, prüft der Browser, ob sich das Skript Byte für Byte geändert hat. Nur dann installiert er eine neue Version. Die neue Version bleibt im Zustand waiting, bis keine Seite mehr von der alten Version gesteuert wird. Das lässt sich im Worker mit self.skipWaiting() und clients.claim() abkürzen.

Du kannst die Methode bei jedem Seitenaufruf gefahrlos aufrufen. Wenn sich nichts geändert hat, gibt sie einfach die vorhandene Registrierung zurück. Üblich ist der Aufruf nach dem load-Event, damit das erste Laden der Seite nicht gebremst wird.

Parameter

Name	Typ	Default	Beschreibung
$scriptURL Pflicht	string \| URL \| TrustedScriptURL		URL des Service-Worker-Skripts. Das Skript muss vom selben Ursprung (Origin) wie die Seite stammen und mit einem JavaScript-MIME-Typ ausgeliefert werden.
$options	object	{}	Optionales Konfigurationsobjekt mit folgenden Feldern: `scope` (`string`): URL-Bereich, den der Worker steuert. Standard ist das Verzeichnis des Skripts. `type` (`"classic" \| "module"`): `"module"` erlaubt `import`-Anweisungen im Worker. Standard ist `"classic"`. `updateViaCache` (`"imports" \| "all" \| "none"`): legt fest, ob der HTTP-Cache bei Update-Prüfungen genutzt wird. Standard ist `"imports"`, d. h. nur importierte Skripte kommen aus dem HTTP-Cache, das Hauptskript nicht.

Rückgabewert

Typ

Promise<ServiceWorkerRegistration>

Beschreibung

Ein Promise, das mit der ServiceWorkerRegistration erfüllt wird. Es wird abgelehnt, z. B. mit SecurityError (unsicherer Kontext, fremder Ursprung, unzulässiger Scope) oder TypeError (Skript nicht ladbar, falscher MIME-Typ, Syntaxfehler).

Beispiele

Grundlegende Registrierung mit Feature-Erkennung

if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js');
      console.log('Service Worker registriert, Scope:', registration.scope);
    } catch (error) {
      console.error('Registrierung fehlgeschlagen:', error);
    }
  });
}

Service Worker registriert, Scope: https://example.com/

Eingeschränkter Scope und ES-Modul-Worker

const registerAppWorker = async () => {
  const registration = await navigator.serviceWorker.register('/app/sw.js', {
    scope: '/app/',
    type: 'module',        // erlaubt import im Worker
    updateViaCache: 'none' // Update-Prüfung immer am HTTP-Cache vorbei
  });
  return registration;
};

registerAppWorker().then((reg) => console.log(reg.scope));

https://example.com/app/

Neue Version erkennen und den Nutzer informieren

const registration = await navigator.serviceWorker.register('/sw.js');

registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  newWorker.addEventListener('statechange', () => {
    // installiert und eine alte Version steuert noch die Seite
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      console.log('Neue Version verfügbar – bitte Seite neu laden.');
    }
  });
});

// Manuell nach Updates suchen, z. B. stündlich
setInterval(() => registration.update(), 60 * 60 * 1000);

Neue Version verfügbar – bitte Seite neu laden.

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Service Worker funktionieren nur über HTTPS oder auf localhost. Über http:// oder file:// ist navigator.serviceWorker undefined bzw. die Registrierung schlägt fehl.
Scope-Falle: Liegt das Skript unter /js/sw.js, kann es ohne den Header Service-Worker-Allowed: / nicht die ganze Seite steuern. Der Aufruf mit scope: '/' endet dann mit SecurityError.
Erste Seite wird nicht gesteuert: Die Seite, die den Worker registriert, wird erst beim nächsten Laden von ihm gesteuert. Ausnahme: Der Worker ruft clients.claim() auf. Bis dahin ist navigator.serviceWorker.controller null.
Caching: Liefere sw.js mit kurzer oder gar keiner HTTP-Cache-Dauer aus, sonst kommen Updates verzögert an. Browser begrenzen die Cache-Nutzung bei Update-Prüfungen zwar auf 24 Stunden, trotzdem ist Cache-Control: no-cache sinnvoll.
Private Modi und Einstellungen: In manchen privaten Fenstern (z. B. bei Firefox) oder wenn Cookies und Website-Daten blockiert sind, lehnt der Browser die Registrierung ab. Fehler also immer abfangen.
Kompatibilität: Alle aktuellen Browser unterstützen die Methode. type: 'module' gibt es in Chromium seit Version 91, in Safari seit 15 und in Firefox erst seit 114.
Sicherheit: Ein Service Worker kann alle Anfragen in seinem Scope abfangen und verändern. Lade das Skript deshalb nie von URLs, die Nutzer beeinflussen können. Unter strenger CSP mit Trusted Types muss scriptURL ein TrustedScriptURL sein.

Siehe auch

Cache ServiceWorkerContainer.getRegistration() ServiceWorkerContainer.getRegistrations() ServiceWorkerContainer.startMessages() ServiceWorkerRegistration.unregister()