Von Workbox v5 zu v6 migrieren

In diesem Leitfaden geht es um die nicht abwärtskompatiblen Änderungen in Workbox v6. Außerdem finden Sie Beispiele für Änderungen, die Sie beim Upgrade von Workbox v5 vornehmen müssen.

Wichtige Änderungen

workbox-core

Die Methode skipWaiting() in workbox-core fügt keinen install-Handler mehr hinzu und entspricht dem Aufruf von self.skipWaiting().

Verwenden Sie stattdessen self.skipWaiting(), da skipWaiting() in Workbox v7 wahrscheinlich entfernt wird.

workbox-precaching

  • Mehrfach-Quell-HTML-Dokumente für URLs, die einer HTTP-Weiterleitung entsprechen, können nicht mehr verwendet werden, um eine Navigationsanfrage mit workbox-precaching zu erfüllen. Dieses Szenario ist in der Regel nicht üblich.
  • Der URL-Abfrageparameter fbclid wird jetzt von workbox-precaching ignoriert, wenn eine vorab im Cache gespeicherte Antwort für eine bestimmte Anfrage gesucht wird.
  • Der PrecacheController-Konstruktor nimmt jetzt ein Objekt mit bestimmten Eigenschaften als Parameter an, anstatt einen String. Dieses Objekt unterstützt die folgenden Eigenschaften: cacheName (dient demselben Zweck wie der String, der in Version 5 an den Konstruktor übergeben wurde), plugins (ersetzt die addPlugins()-Methode aus Version 5) und fallbackToNetwork (ersetzt die ähnliche Option, die in Version 5 an createHandler() und „createHandlerBoundToURL()“ übergeben wurde).
  • Die Methoden install() und activate() von PrecacheController nehmen jetzt genau einen Parameter an, der auf einen entsprechenden InstallEvent oder ActivateEvent gesetzt werden sollte.
  • Die Methode addRoute() wurde aus PrecacheController entfernt. Stattdessen kann die neue Klasse PrecacheRoute verwendet werden, um eine Route zu erstellen, die Sie dann registrieren können.
  • Die Methode precacheAndRoute() wurde aus PrecacheController entfernt. Sie existiert weiterhin als statische Hilfsmethode, die vom workbox-precaching-Modul exportiert wird. Sie wurde entfernt, da stattdessen PrecacheRoute verwendet werden kann.
  • Die Methode createMatchCalback() wurde aus PrecacheController entfernt. Stattdessen kann das neue PrecacheRoute verwendet werden.
  • Die Methode createHandler() wurde aus PrecacheController entfernt. Stattdessen kann die Property strategy des PrecacheController-Objekts verwendet werden, um Anfragen zu verarbeiten.
  • Der statische createHandler()-Export wurde bereits aus dem workbox-precaching-Modul entfernt. Stattdessen sollten Entwickler eine PrecacheController-Instanz erstellen und das strategy-Attribut verwenden.
  • Die bei precacheAndRoute() registrierte Route ist jetzt eine „echte“ Route, die die Router-Klasse von workbox-routing verwendet. Dies kann zu einer anderen Auswertungsreihenfolge Ihrer Routes führen, wenn Sie Aufrufe von registerRoute() und precacheAndRoute() verschachteln.

workbox-routing

Die setDefaultHandler()-Methode nimmt jetzt einen optionalen zweiten Parameter entgegen, der der HTTP-Methode entspricht, auf die sie angewendet wird. Standardmäßig ist das 'GET'.

  • Wenn Sie setDefaultHandler() verwenden und alle Ihre Anfragen GET sind, müssen Sie nichts ändern.
  • Wenn du Anfragen hast, die nicht GET sind (POST, PUT usw.), setDefaultHandler() führt nicht mehr dazu, dass diese Anfragen übereinstimmen.

Build-Konfiguration

Die Option mode für die Modi getManifest und injectManifest in workbox-build und workbox-cli wurde nicht unterstützt und wurde entfernt. Das gilt nicht für workbox-webpack-plugin, das mode in seinem InjectManifest-Plug-in unterstützt.

Für Build-Tools ist Node.js 10 oder höher erforderlich

Node.js-Versionen vor Version 10 werden für workbox-webpack-plugin, workbox-build und workbox-cli nicht mehr unterstützt. Wenn Sie eine Version von Node.js vor Version 8 ausführen, aktualisieren Sie die Laufzeit auf eine unterstützte Version.

Neue Verbesserungen

workbox-strategies

Mit Workbox v6 können Entwickler von Drittanbietern ihre eigenen Workbox-Strategien definieren. So können Drittanbieter Workbox so erweitern, dass sie ihren Anforderungen voll und ganz entspricht.

Neue Basisklasse für Strategie

In Version 6 müssen alle Workbox-Strategieklassen die neue Basisklasse Strategy erweitern. Alle vordefinierten Strategien wurden entsprechend überarbeitet.

Die Basisklasse Strategy ist für zwei Hauptaufgaben verantwortlich:

  • Aufruf von Callbacks für den Lebenszyklus von Plug-ins, die für alle Strategie-Handler gemeinsam sind (z.B. beim Starten, Antworten und Beenden).
  • Erstellen einer „Handler“-Instanz, die den Status für jede einzelne Anfrage verwalten kann, die von einer Strategie verarbeitet wird.

Neue „handler“-Klasse

Bisher gab es die internen Module fetchWrapper und cacheWrapper, die (wie der Name schon sagt) die verschiedenen Abruf- und Cache-APIs mit Hooks in ihren Lebenszyklus einbetten. Dieser Mechanismus ermöglicht derzeit die Funktion von Plug-ins, ist aber für Entwickler nicht sichtbar.

Die neue „handler“-Klasse StrategyHandler stellt diese Methoden zur Verfügung, damit benutzerdefinierte Strategien fetch() oder cacheMatch() aufrufen und alle Plugins, die der Strategieinstanz hinzugefügt wurden, automatisch aufgerufen werden können.

Diese Klasse würde es Entwicklern auch ermöglichen, eigene benutzerdefinierte Lebenszyklus-Callbacks hinzuzufügen, die für ihre Strategien spezifisch sein könnten, und sie würden „einfach“ mit der vorhandenen Plug-in-Benutzeroberfläche funktionieren.

Neuer Lebenszyklusstatus des Plug-ins

In Workbox v5 sind Plug-ins zustandslos. Das bedeutet, dass diese beiden Callbacks nicht miteinander kommunizieren können, wenn eine Anfrage für /index.html sowohl den requestWillFetch- als auch den cachedResponseWillBeUsed-Callback auslöst. Sie können nicht einmal wissen, dass sie von derselben Anfrage ausgelöst wurden.

In Version 6 wird allen Plug-in-Callbacks auch ein neues state-Objekt übergeben. Dieses Statusobjekt ist für dieses bestimmte Plug-in-Objekt und diesen bestimmten Strategieaufruf (d.h. den Aufruf von handle()) eindeutig. So können Entwickler Plug-ins schreiben, in denen ein Callback bedingt etwas tun kann, je nachdem, was ein anderer Callback im selben Plug-in getan hat (z.B. das Zeitdelta zwischen dem Ausführen von requestWillFetch und fetchDidSucceed oder fetchDidFail berechnen).

Neue Callbacks für den Plug-in-Lebenszyklus

Es wurden neue Lebenszyklus-Callbacks für Plug-ins hinzugefügt, damit Entwickler den Lebenszyklusstatus des Plug-ins optimal nutzen können:

  • handlerWillStart: Wird aufgerufen, bevor die Logik des Handlers ausgeführt wird. Mit diesem Rückruf kann der anfängliche Handlerstatus festgelegt werden (z.B. die Startzeit aufzeichnen).
  • handlerWillRespond: Wird aufgerufen, bevor die Strategiemethode handle() eine Antwort zurückgibt. Mit diesem Callback kann diese Antwort geändert werden, bevor sie an einen Routen-Handler oder eine andere benutzerdefinierte Logik zurückgegeben wird.
  • handlerDidRespond: Wird aufgerufen, nachdem die handle()-Methode der Strategie eine Antwort zurückgegeben hat. Mit diesem Rückruf können alle Details der endgültigen Antwort aufgezeichnet werden, z.B. nach Änderungen, die von anderen Plug-ins vorgenommen wurden.
  • handlerDidComplete: Wird aufgerufen, nachdem alle Versprechen zur Verlängerung der Lebensdauer, die dem Ereignis durch die Aufrufung dieser Strategie hinzugefügt wurden, abgelaufen sind. Mit diesem Rückruf können Daten erfasst werden, die erst berechnet werden können, wenn der Handler fertig ist (z.B. Cache-Trefferstatus, Cache-Latenz, Netzwerklatenz).
  • handlerDidError: Wird aufgerufen, wenn der Handler keine gültige Antwort von einer Quelle liefern konnte. Mit diesem Rückruf können Sie als Alternative zu einem Netzwerkfehler „Fallback“-Inhalte bereitstellen.

Entwickler, die ihre eigenen benutzerdefinierten Strategien implementieren, müssen sich nicht darum kümmern, diese Callbacks selbst aufzurufen. Das wird alles von einer neuen Strategy-Basisklasse erledigt.

Genauere TypeScript-Typen für Handler

TypeScript-Definitionen für verschiedene Callback-Methoden wurden normalisiert. Dies sollte die Arbeit für Entwickler erleichtern, die TypeScript verwenden und eigenen Code zum Implementieren oder Aufrufen von Handlers schreiben.

workbox-window

Neue Methode „messageSkipWaiting()“

Dem workbox-window-Modul wurde die neue Methode messageSkipWaiting() hinzugefügt, um die Aktivierung des wartenden Dienst-Workers zu vereinfachen. Das bietet einige Verbesserungen:

  • Er ruft postMessage() mit dem de-facto-Standardnachrichtentext {type: 'SKIP_WAITING'} auf, den ein von Workbox generierter Dienst-Worker prüft, um skipWaiting() auszulösen.
  • Es wird der richtige „wartende“ Service Worker ausgewählt, an den diese Nachricht gesendet werden soll, auch wenn es sich nicht um denselben Service Worker handelt, bei dem workbox-window registriert wurde.

Entfernung von „externen“ Ereignissen zugunsten des Attributs „isExternal“

Alle externen Ereignisse in workbox-window wurden entfernt und durch „normale“ Ereignisse ersetzt, für die die isExternal-Eigenschaft auf true festgelegt ist. So können Entwickler, die die Unterscheidung benötigen, sie weiterhin erkennen. Entwickler, die sie nicht benötigen, können die Property ignorieren.

Optimiertes Rezept „Nutzer eine Seite neu laden lassen“

Dank der beiden oben genannten Änderungen kann das Rezept Seitenaktualisierung für Nutzer anbieten vereinfacht werden:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

workbox-routing

Der neuen Funktion matchCallback, die in workbox-routing verwendet wird, wird der boolesche Parameter sameOrigin übergeben. Der Wert ist auf true festgelegt, wenn es sich bei der Anfrage um eine URL mit demselben Ursprung handelt, andernfalls auf „falsch“.

Dadurch wird einige gängige Boilerplate-Codefragmente vereinfacht:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

matchOptions in workbox-expiration

Sie können jetzt matchOptions in workbox-expiration festlegen, was dann als CacheQueryOptions an den zugrunde liegenden cache.delete()-Aufruf übergeben wird. (Die meisten Entwickler müssen das nicht tun.)

workbox-precaching

Verwendet Workbox-Strategien

workbox-precaching wurde so umgeschrieben, dass workbox-strategies als Basis verwendet wird. Dies sollte keine bahnbrechenden Änderungen zur Folge haben und zu einer besseren langfristigen Konsistenz bei der Zugriffsweise der beiden Module auf das Netzwerk und den Cache führen.

Beim Precaching werden Einträge jetzt einzeln und nicht mehr im Bulk verarbeitet

workbox-precaching wurde aktualisiert, sodass jeweils nur ein Eintrag im Pre-Cache-Manifest angefordert und im Cache gespeichert wird, anstatt alle gleichzeitig anzufordern und im Cache zu speichern. Die Drosselung wird dem Browser überlassen.

Dadurch sollte die Wahrscheinlichkeit von net::ERR_INSUFFICIENT_RESOURCES-Fehlern beim Precaching verringert und die Bandbreitenauslastung zwischen Precaching und gleichzeitigen Anfragen der Webanwendung reduziert werden.

PrecacheFallbackPlugin ermöglicht einfacheren Offline-Fallback

workbox-precaching enthält jetzt eine PrecacheFallbackPlugin, die die neue Lebenszyklusmethode handlerDidError implementiert, die in Version 6 hinzugefügt wurde.

So lässt sich ganz einfach eine vorab im Cache gespeicherte URL als „Fallback“ für eine bestimmte Strategie angeben, wenn eine Antwort andernfalls nicht verfügbar wäre. Das Plug-in sorgt dafür, dass der richtige Cache-Schlüssel für die vorab im Cache gespeicherte URL erstellt wird, einschließlich aller erforderlichen Revisionen.

Hier ein Beispiel dafür, wie damit mit einer vorab im Cache gespeicherten /offline.html geantwortet wird, wenn die NetworkOnly-Strategie keine Antwort für eine Navigationsanfrage generieren kann, d. h. eine benutzerdefinierte Offline-HTML-Seite angezeigt wird:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback im Laufzeit-Caching

Wenn Sie generateSW verwenden, um einen Service Worker für Sie zu erstellen, anstatt ihn manuell zu schreiben, können Sie die neue precacheFallback-Konfigurationsoption in runtimeCaching verwenden, um dasselbe zu erreichen:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

Hilfe erhalten

Wir gehen davon aus, dass die meisten Migrationen unkompliziert sind. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, erstelle bitte einen Issue auf GitHub.