ServiceWorkerRegistration: updatefound — Ereignis · JavaScript-Referenz

Signatur

registration.addEventListener("updatefound", handler)

Beschreibung

Das Ereignis updatefound tritt an einem ServiceWorkerRegistration-Objekt auf, sobald der Browser eine neue Version des Service-Worker-Skripts gefunden hat und mit deren Installation beginnt. Im gleichen Moment wird die Eigenschaft registration.installing auf den neuen ServiceWorker gesetzt. Das passiert auch bei der allerersten Registrierung, nicht nur bei späteren Aktualisierungen.

Typischer Einsatz: Du willst Nutzern Bescheid geben, dass eine neue Version der Web-App bereitsteht („Update verfügbar – neu laden?“). Dafür registrierst du im updatefound-Handler einen statechange-Listener am neuen Worker und prüfst, ob er den Zustand installed erreicht. Hat die Seite zu diesem Zeitpunkt schon einen aktiven Controller (navigator.serviceWorker.controller), handelt es sich um ein Update. Fehlt er, war es die Erstinstallation.

Du kannst den Handler per addEventListener("updatefound", handler) oder über die Eigenschaft registration.onupdatefound setzen. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten, blubbert nicht und lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"updatefound"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie bekommt ein einfaches `Event`-Objekt. Den neuen Worker liest du über `registration.installing` aus.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück.

Beispiele

Neue Version erkennen und Nutzer benachrichtigen

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

registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  console.log('Neuer Service Worker wird installiert');

  newWorker.addEventListener('statechange', () => {
    if (newWorker.state === 'installed') {
      if (navigator.serviceWorker.controller) {
        console.log('Update verfügbar – bitte Seite neu laden.');
      } else {
        console.log('Inhalte sind jetzt offline verfügbar.');
      }
    }
  });
});

Neuer Service Worker wird installiert Update verfügbar – bitte Seite neu laden.

Handler über die on-Property setzen

const registration = await navigator.serviceWorker.getRegistration();

if (registration) {
  registration.onupdatefound = () => {
    console.log('Installationsstatus:', registration.installing?.state);
  };
  // Update-Prüfung manuell anstoßen
  await registration.update();
}

Installationsstatus: installing

Update auf Knopfdruck aktivieren und Listener wieder entfernen

const registration = await navigator.serviceWorker.register('/sw.js');
const button = document.querySelector('#update-button');

const onUpdateFound = () => {
  const worker = registration.installing;
  worker.addEventListener('statechange', () => {
    if (worker.state === 'installed' && navigator.serviceWorker.controller) {
      button.hidden = false;
      button.onclick = () => worker.postMessage({ type: 'SKIP_WAITING' });
    }
  });
  // nur auf das erste Update reagieren
  registration.removeEventListener('updatefound', onUpdateFound);
};

registration.addEventListener('updatefound', onUpdateFound);

// Neu laden, sobald der neue Worker die Kontrolle übernimmt
navigator.serviceWorker.addEventListener('controllerchange', () => location.reload());

// Wichtig · Fallstricke

Erstinstallation: updatefound feuert auch bei der ersten Registrierung. Ob es wirklich ein Update ist, erkennst du an navigator.serviceWorker.controller.
Zeitpunkt: Das Ereignis heißt nur, dass die Installation beginnt. Sie kann trotzdem scheitern, dann wechselt der Worker in den Zustand redundant. Verlass dich deshalb auf statechange.
Listener zu spät angemeldet: Setzt du den Listener erst, nachdem die Installation schon läuft, verpasst du das Ereignis. Prüfe dann zusätzlich direkt registration.installing und registration.waiting.
Update-Prüfung: Der Browser sucht bei Navigationen nach Updates, höchstens aber alle 24 Stunden unter Umgehung des HTTP-Caches. Mit registration.update() stößt du die Prüfung selbst an. Schon ein einziges geändertes Byte im Skript gilt als neue Version.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Service Worker brauchen einen sicheren Kontext (HTTPS oder localhost) und fehlen z. B. in manchen privaten Fenstern.

Siehe auch

BackgroundFetchRegistration: progress ServiceWorker: statechange ServiceWorkerContainer: message ServiceWorkerContainer: messageerror ServiceWorkerGlobalScope: push