Migreren van Workbox v5 naar v6

Deze gids is gericht op de schadelijke wijzigingen die zijn geïntroduceerd in Workbox v6, met voorbeelden van de wijzigingen die je moet aanbrengen als je een upgrade uitvoert vanaf Workbox v5.

Schadelijke wijzigingen

workbox-core

De methode skipWaiting() in workbox-core voegt geen install-handler meer toe en is gelijk aan het aanroepen van self.skipWaiting().

Gebruik vanaf nu self.skipWaiting(), omdat skipWaiting() waarschijnlijk wordt verwijderd in Workbox v7.

workbox-precaching

• Cross-origin HTML-documenten voor URL's die overeenkomen met een HTTP-omleiding kunnen niet meer worden gebruikt om te voldoen aan een navigatieverzoek met workbox-precaching. Dit scenario komt over het algemeen niet vaak voor.
• De URL-queryparameter fbclid wordt nu genegeerd door workbox-precaching als er een vooraf in het cachegeheugen opgeslagen reactie voor een bepaald verzoek wordt opgezocht.
• De PrecacheController-constructor gebruikt nu een object met specifieke eigenschappen als parameter in plaats van een tekenreeks. Dit object ondersteunt de volgende eigenschappen: cacheName (met hetzelfde doel als de tekenreeks die is doorgegeven aan de constructor in v5), plugins (vervangt de addPlugins()-methode uit v5) en fallbackToNetwork (vervangt de vergelijkbare optie die is doorgegeven aan createHandler() en `createHandlerBoundToURL() in v5).
• De methoden install() en activate() van PrecacheController nemen nu precies één parameter, die respectievelijk moet worden ingesteld op een overeenkomstige InstallEvent of ActivateEvent.
• De methode addRoute() is verwijderd uit PrecacheController. In plaats daarvan kan de nieuwe klasse PrecacheRoute worden gebruikt om een route te maken die je daarna kunt registreren.
• De methode precacheAndRoute() is verwijderd uit PrecacheController. (De methode bestaat nog steeds als statische hulpmethode die wordt geëxporteerd door de module workbox-precaching.) De functie is verwijderd omdat je in plaats daarvan PrecacheRoute kunt gebruiken.
• De methode createMatchCalback() is verwijderd uit PrecacheController. U kunt in plaats daarvan de nieuwe PrecacheRoute gebruiken.
• De methode createHandler() is verwijderd uit PrecacheController. In plaats daarvan kun je de property strategy van het object PrecacheController gebruiken om verzoeken te verwerken.
• De statische export createHandler() is al verwijderd uit de module workbox-precaching. In plaats daarvan moeten ontwikkelaars een PrecacheController-instantie maken en de property strategy gebruiken.
• De route die is geregistreerd bij precacheAndRoute() is nu een echte route die de klasse Router van workbox-routing gebruikt. Dit kan leiden tot een andere evaluatievolgorde van je routes als je aanroepen naar registerRoute() en precacheAndRoute() afwisselt.

workbox-routing

De methode setDefaultHandler() heeft nu een optionele 2e parameter die overeenkomt met de HTTP-methode waarop deze van toepassing is. De standaardwaarde is 'GET'.

• Als u setDefaultHandler() gebruikt en al uw verzoeken GET zijn, hoeft u geen wijzigingen aan te brengen.
• Als je verzoeken hebt die niet GET zijn (POST, PUT, enzovoort), setDefaultHandler() zorgt er niet meer voor dat die verzoeken overeenkomen.

Buildconfiguratie

De optie mode voor de modi getManifest en injectManifest in workbox-build en workbox-cli was niet bedoeld om te worden ondersteund en is verwijderd. Dit is niet van toepassing op workbox-webpack-plugin, die wel mode ondersteunt in de InjectManifest-plug-in.

Voor Build Tools is Node.js v10 of hoger vereist

Node.js-versies ouder dan v10 worden niet meer ondersteund voor workbox-webpack-plugin, workbox-build of workbox-cli. Als u een versie van Node.js gebruikt die ouder is dan v8, updatet u de runtime naar een ondersteunde versie.

Nieuwe verbeteringen

workbox-strategies

Workbox v6 introduceert een nieuwe manier voor externe ontwikkelaars om hun eigen Workbox-strategieën te definiëren. Zo kunnen externe ontwikkelaars Workbox uitbreiden op manieren die volledig aan hun behoeften voldoen.

Nieuwe basisklasse voor strategie

In v6 moeten alle Workbox-strategieklassen de nieuwe basisklasse Strategy uitbreiden. Alle ingebouwde strategieën zijn herschreven om dit te ondersteunen.

De basisklasse Strategy is verantwoordelijk voor 2 primaire zaken:

• Levenscyclus-callbacks van plug-ins aanroepen die gemeenschappelijk zijn voor alle strategiehandlers (bijvoorbeeld wanneer ze starten, reageren en eindigen).
• Een handler-instantie maken die de status kan beheren voor elk afzonderlijk verzoek dat een strategie verwerkt.

Nieuwe handler-klasse

We hadden eerder interne modules met de naam fetchWrapper en cacheWrapper, die (zoals de naam al aangeeft) de verschillende fetch- en cache-API's verpakken met hooks in hun levenscyclus. Dit is het mechanisme waarmee plug-ins op dit moment kunnen werken, maar het is niet beschikbaar voor ontwikkelaars.

De nieuwe handler-klasse, StrategyHandler, maakt deze methoden beschikbaar, zodat aangepaste strategieën fetch() of cacheMatch() kunnen aanroepen en plug-ins die aan de strategie-instantie zijn toegevoegd, automatisch worden aangeroepen.

Met deze klasse kunnen ontwikkelaars ook hun eigen aangepaste levenscyclus-callbacks toevoegen die specifiek zijn voor hun strategieën. Deze werken dan gewoon met de bestaande plug-ininterface.

Nieuwe levenscyclusstatus van plug-in

In Workbox v5 zijn plug-ins stateless. Dit betekent dat als een verzoek voor /index.html zowel de callback requestWillFetch als de callback cachedResponseWillBeUsed activeert, deze 2 callbacks niet met elkaar kunnen communiceren en zelfs niet weten dat ze door hetzelfde verzoek zijn geactiveerd.

In v6 wordt aan alle plugin-callbacks ook een nieuw state-object doorgegeven. Dit statusobject is uniek voor dit specifieke plug-inobject en deze specifieke strategieaanroep (dat wil zeggen de aanroep van handle()). Hierdoor kunnen ontwikkelaars plug-ins schrijven waarbij een callback voorwaardelijk iets kan doen op basis van wat een andere callback in dezelfde plug-in heeft gedaan (bijvoorbeeld het tijdsverschil berekenen tussen de uitvoering van requestWillFetch en fetchDidSucceed of fetchDidFail).

Nieuwe levenscyclus-callbacks voor plug-ins

Er zijn nieuwe levenscyclus-callbacks voor plug-ins toegevoegd, zodat ontwikkelaars de levenscyclusstatus van de plug-in volledig kunnen benutten:

• handlerWillStart: wordt aangeroepen voordat de logica van de handler wordt uitgevoerd. Deze callback kan worden gebruikt om de beginstatus van de handler in te stellen (bijvoorbeeld de begintijd registreren).
• handlerWillRespond: wordt aangeroepen voordat de methode strategies handle() een reactie retourneert. Deze callback kan worden gebruikt om die reactie aan te passen voordat deze wordt geretourneerd naar een routehandler of andere aangepaste logica.
• handlerDidRespond: wordt aangeroepen nadat de methode handle() van de strategie een reactie heeft geretourneerd. Deze callback kan worden gebruikt om de uiteindelijke reactiegegevens vast te leggen, bijvoorbeeld na wijzigingen die door andere plug-ins zijn aangebracht.
• handlerDidComplete: wordt aangeroepen nadat alle extend lifetime promises die aan de gebeurtenis zijn toegevoegd door de aanroep van deze strategie, zijn afgehandeld. Deze callback kan worden gebruikt om te rapporteren over gegevens die moeten wachten tot de handler klaar is om te berekenen (bijvoorbeeld de status van aanwezig in cache, cachelatentie, netwerklatentie).
• handlerDidError: Wordt aangeroepen als de handler geen geldige reactie van een bron kan leveren. Deze callback kan worden gebruikt om fallback-content te bieden als alternatief voor een netwerkfout.

Ontwikkelaars die hun eigen aangepaste strategieën implementeren, hoeven deze callbacks niet zelf aan te roepen. Dat wordt allemaal afgehandeld door een nieuwe basisklasse Strategy.

Nauwkeurigere TypeScript-typen voor handlers

TypeScript-definities voor verschillende callbackmethoden zijn genormaliseerd. Dit zou moeten leiden tot een betere gebruikerservaring voor ontwikkelaars die TypeScript gebruiken en hun eigen code schrijven om handlers te implementeren of aan te roepen.

workbox-window

Nieuwe methode messageSkipWaiting()

Er is een nieuwe methode, messageSkipWaiting(), toegevoegd aan de module workbox-window om het proces te vereenvoudigen om de "wachtende" servicemedewerker te vertellen dat deze moet worden geactiveerd. Dit biedt een aantal verbeteringen:

• De functie roept postMessage() aan met de de facto standaard berichttekst, {type: 'SKIP_WAITING'}, die een door Workbox gegenereerde serviceworker controleert om skipWaiting() te activeren.
• De juiste 'wachtende' serviceworker wordt gekozen om dit bericht naar te posten, zelfs als dit niet dezelfde serviceworker is waarmee workbox-window is geregistreerd.

Verwijdering van externe gebeurtenissen ten gunste van een isExternal-property

Alle externe gebeurtenissen in workbox-window zijn verwijderd en vervangen door normale gebeurtenissen met een isExternal-property die is ingesteld op true. Zo kunnen ontwikkelaars die het onderscheid belangrijk vinden, dit nog steeds detecteren en kunnen ontwikkelaars die dit niet hoeven te weten, de property negeren.

Duidelijker recept voor 'Gebruikers aanbieden de pagina opnieuw te laden'

Dankzij de 2 wijzigingen hierboven kan het recept Gebruikers aanbieden de pagina opnieuw te laden worden vereenvoudigd:

// 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

Er wordt een nieuwe booleaanse parameter, sameOrigin, doorgegeven aan de functie matchCallback die wordt gebruikt in workbox-routing. De waarde wordt ingesteld op true als het verzoek een URL met dezelfde oorsprong betreft, anders wordt die ingesteld op onwaar.

Dit vereenvoudigt een aantal veelvoorkomende standaardteksten:

// 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

U kunt nu matchOptions instellen in workbox-expiration. Dit wordt dan doorgegeven als de CacheQueryOptions aan de onderliggende cache.delete()-aanroep. (De meeste ontwikkelaars hoeven dit niet te doen.)

workbox-precaching

Gebruikt workbox-strategies

workbox-precaching is herschreven om workbox-strategies als basis te gebruiken. Dit zou niet tot schadelijke wijzigingen moeten leiden en zou op de lange termijn moeten leiden tot een betere consistentie in de manier waarop de twee modules toegang hebben tot het netwerk en de cache.

Precaching verwerkt items nu één voor één, niet in bulk

workbox-precaching is geüpdatet zodat er maar één item in het precache-manifest tegelijk wordt aangevraagd en gecachet, in plaats van dat ze allemaal tegelijk worden aangevraagd en gecachet (waarbij het aan de browser wordt overgelaten om te bepalen hoe de snelheid wordt beperkt).

Dit verkleint de kans op net::ERR_INSUFFICIENT_RESOURCES-fouten tijdens het vooraf opslaan in het cachegeheugen en vermindert ook de bandbreedteconcurrentie tussen vooraf opslaan in het cachegeheugen en gelijktijdige verzoeken van de web-app.

PrecacheFallbackPlugin maakt een makkelijkere offline fallback mogelijk

workbox-precaching bevat nu een PrecacheFallbackPlugin, die de nieuwe levenscyclusmethode handlerDidError implementeert die is toegevoegd in v6.

Zo kun je makkelijk een vooraf gecachte URL opgeven als 'fallback' voor een bepaalde strategie als er anders geen reactie beschikbaar zou zijn. De plug-in zorgt ervoor dat de juiste cachesleutel voor de vooraf gecachte URL wordt samengesteld, inclusief de benodigde revisieparameter.

Hier is een voorbeeld van hoe je dit gebruikt om te reageren met een vooraf gecachte /offline.html als de NetworkOnly-strategie geen reactie kan genereren voor een navigatieverzoek. Met andere woorden: een aangepaste offline HTML-pagina tonen:

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 in runtime-caching

Als je generateSW gebruikt om een serviceworker voor je te maken in plaats van je serviceworker handmatig te schrijven, kun je de nieuwe configuratieoptie precacheFallback in runtimeCaching gebruiken om hetzelfde te bereiken:

{
  // ... 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',
      },
    },
  }],
}

Ondersteuning vragen

We verwachten dat de meeste migraties eenvoudig zullen zijn. Als u problemen ondervindt die niet in deze gids worden behandeld, laat u ons dit weten door een probleem te openen op GitHub.