Migreer van Workbox v5 naar v6

Deze handleiding is gericht op het doorbreken van de wijzigingen die in Workbox v6 zijn geïntroduceerd, met voorbeelden van de wijzigingen die u moet aanbrengen bij het upgraden van Workbox v5.

Veranderingen doorbreken

werkdoos-kern

De methode skipWaiting() in workbox-core voegt niet langer een install toe en is gelijk aan het gewoon aanroepen van self.skipWaiting() .

Gebruik vanaf nu in plaats daarvan self.skipWaiting() omdat skipWaiting() waarschijnlijk zal worden verwijderd in Workbox v7.

precaching van werkvakken

  • Cross-origin HTML-documenten voor URL's die overeenkomen met een HTTP-omleiding kunnen niet langer worden gebruikt om te voldoen aan een navigatieverzoek met workbox-precaching . Dit scenario is over het algemeen ongebruikelijk.
  • De URL-queryparameter fbclid wordt nu genegeerd door workbox-precaching bij het opzoeken van een vooraf in de cache opgeslagen antwoord voor een bepaald verzoek.
  • De PrecacheController -constructor neemt nu een object met specifieke eigenschappen als parameter op, in plaats van een string. Dit object ondersteunt de volgende eigenschappen: cacheName (die hetzelfde doel dient als de tekenreeks die in v5 aan de constructor is doorgegeven), plugins (ter vervanging van de methode addPlugins() uit v5) en fallbackToNetwork (ter vervanging van de vergelijkbare optie die is doorgegeven aan createHandler() en `createHandlerBoundToURL() in v5).
  • De methoden install() en activate() van PrecacheController gebruiken nu precies één parameter, die moet worden ingesteld op respectievelijk 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 u vervolgens kunt registreren.
  • De methode precacheAndRoute() is verwijderd uit PrecacheController . (Het bestaat nog steeds als een statische hulpmethode die wordt geëxporteerd door de workbox-precaching module.) Het is verwijderd omdat PrecacheRoute in plaats daarvan kan worden gebruikt.
  • De methode createMatchCalback() is verwijderd uit PrecacheController . In plaats daarvan kan de nieuwe PrecacheRoute worden gebruikt.
  • De methode createHandler() is verwijderd uit PrecacheController . De strategy eigenschap van het PrecacheController object kan in plaats daarvan worden gebruikt om verzoeken af ​​te handelen.
  • De statische export createHandler() is al verwijderd uit de workbox-precaching -module. In plaats daarvan zouden ontwikkelaars een PrecacheController instantie moeten bouwen en de bijbehorende strategy eigenschap moeten gebruiken.
  • De route die is geregistreerd bij precacheAndRoute() is nu een "echte" route die gebruikmaakt van de Router -klasse van workbox-routing onder de motorkap. Dit kan leiden tot een andere evaluatievolgorde van uw routes als u aanroepen naar registerRoute() en precacheAndRoute() tussenvoegt.

werkdoos-routing

De methode setDefaultHandler() gebruikt nu een optionele tweede parameter die overeenkomt met de HTTP-methode waarop deze van toepassing is, standaard ingesteld op 'GET' .

  • Als u setDefaultHandler() gebruikt en al uw verzoeken GET zijn, hoeven er geen wijzigingen te worden aangebracht.
  • Als u verzoeken heeft die niet GET zijn ( POST , PUT , enz...), zal setDefaultHandler() er niet langer voor zorgen dat deze verzoeken overeenkomen.

Configuratie bouwen

De 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 mode ondersteunt in de InjectManifest -plug-in.

Bouwtools vereisen Node.js v10 of hoger

Node.js-versies vóór v10 worden niet langer ondersteund voor workbox-webpack-plugin , workbox-build of workbox-cli . Als u een eerdere versie van Node.js dan v8 gebruikt, update dan uw runtime naar een ondersteunde versie .

Nieuwe verbeteringen

workbox-strategieën

Workbox v6 introduceert een nieuwe manier voor externe ontwikkelaars om hun eigen Workbox-strategieën te definiëren. Dit zorgt ervoor dat externe ontwikkelaars de mogelijkheid hebben om Workbox uit te breiden op manieren die volledig aan hun behoeften voldoen.

Nieuwe strategie-basisklasse

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

De basisklasse Strategy is verantwoordelijk voor twee belangrijke zaken:

  • Het aanroepen van callbacks voor de levenscyclus van plug-ins die gemeenschappelijk zijn voor alle strategiehandlers (bijvoorbeeld wanneer ze starten, reageren en eindigen).
  • Het creëren van een "handler"-instantie, die de status kan beheren voor elk individueel verzoek dat een strategie afhandelt.

Nieuwe klasse "handler".

We hadden voorheen interne modules fetchWrapper en cacheWrapper aanroepen, die (zoals hun naam al aangeeft) de verschillende fetch- en cache-API's met hooks in hun levenscyclus omsluiten. Dit is het mechanisme waardoor plug-ins momenteel kunnen werken, maar dit is niet zichtbaar voor ontwikkelaars.

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

Deze klasse zou het voor ontwikkelaars ook mogelijk maken om hun eigen aangepaste levenscyclus-callbacks toe te voegen die specifiek kunnen zijn voor hun strategieën, en ze zouden "gewoon werken" met de bestaande plug-ininterface.

Nieuwe levenscyclusstatus van plug-in

In Workbox v5 zijn plug-ins staatloos. Dat betekent dat als een verzoek om /index.html zowel de requestWillFetch als cachedResponseWillBeUsed callbacks activeert, deze twee callbacks niet met elkaar kunnen communiceren of zelfs maar weten dat ze door hetzelfde verzoek zijn geactiveerd.

In v6 krijgen alle callbacks van plug-ins ook een nieuw state doorgegeven. Dit statusobject zal uniek zijn voor dit specifieke plug-inobject en deze specifieke strategieaanroep (dat wil zeggen de aanroep van handle() ). Hierdoor kunnen ontwikkelaars plug-ins schrijven waarbij één callback voorwaardelijk iets kan doen op basis van wat een andere callback in dezelfde plug-in deed (bijvoorbeeld de tijdsdelta berekenen tussen het uitvoeren requestWillFetch en fetchDidSucceed of fetchDidFail ).

Nieuwe callbacks voor de levenscyclus van plug-ins

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

  • handlerWillStart : aangeroepen voordat een handlerlogica begint te draaien. Deze callback kan worden gebruikt om de initiële afhandelingsstatus in te stellen (bijvoorbeeld de starttijd vastleggen).
  • handlerWillRespond : aangeroepen voordat de strategie handle() methode een antwoord retourneert. Deze callback kan worden gebruikt om dat antwoord te wijzigen voordat het wordt teruggestuurd naar een route-handler of andere aangepaste logica.
  • handlerDidRespond : aangeroepen nadat de handle() -methode van de strategie een antwoord retourneert. Deze callback kan worden gebruikt om eventuele details van het definitieve antwoord vast te leggen, bijvoorbeeld na wijzigingen die door andere plug-ins zijn aangebracht.
  • handlerDidComplete : aangeroepen nadat alle verlengingsbeloften die aan de gebeurtenis zijn toegevoegd vanaf het aanroepen van deze strategie, zijn afgehandeld. Deze callback kan worden gebruikt om te rapporteren over alle gegevens die moeten wachten totdat de handler klaar is om de berekening uit te voeren (bijvoorbeeld cachehitstatus, cachelatentie, netwerklatentie).
  • handlerDidError : aangeroepen als de handler geen geldig antwoord van welke bron dan ook kon geven. Deze callback kan worden gebruikt om "fallback"-inhoud te bieden als alternatief voor een netwerkfout.

Ontwikkelaars die hun eigen aangepaste strategieën implementeren, hoeven zich geen zorgen te maken over het zelf aanroepen van deze callbacks; dat wordt allemaal afgehandeld door een nieuwe Strategy basisklasse.

Nauwkeurigere TypeScript-typen voor handlers

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

werkbox-venster

Nieuwe messageSkipWaiting()-methode

Een nieuwe methode, messageSkipWaiting() , is toegevoegd aan de workbox-window -module om het proces van het vertellen aan de "wachtende" servicemedewerker om te activeren te vereenvoudigen. Dit biedt enkele verbeteringen:

  • Het roept postMessage() aan met de de facto standaard berichttekst, {type: 'SKIP_WAITING'} , waar een door Workbox gegenereerde servicemedewerker op controleert om skipWaiting() te activeren.
  • Het kiest de juiste "wachtende" servicemedewerker naar wie dit bericht moet worden gepost, zelfs als het niet dezelfde servicemedewerker is waarmee het workbox-window is geregistreerd.

Verwijdering van "externe" gebeurtenissen ten gunste van een isExternal-eigenschap

Alle "externe" gebeurtenissen in workbox-window zijn verwijderd in plaats van "normale" gebeurtenissen waarbij de eigenschap isExternal is ingesteld op true . Hierdoor kunnen ontwikkelaars die het onderscheid belangrijk vinden het nog steeds detecteren, en kunnen ontwikkelaars die het niet hoeven te weten de eigenschap negeren.

Schoner Recept "Bied een herlaadpagina aan voor gebruikers".

Dankzij beide bovenstaande wijzigingen kan het recept voor het aanbieden van een paginaherladen voor gebruikers worden vereenvoudigd:

MULTI_LINE_CODE_PLACEHOLDER_0

werkdoos-routing

Een nieuwe Booleaanse parameter, sameOrigin , wordt doorgegeven aan de matchCallback functie die wordt gebruikt in workbox-routing . Het is ingesteld op true als het verzoek betrekking heeft op een URL van dezelfde oorsprong, en anders op 'false'.

Dit vereenvoudigt een aantal veelvoorkomende standaardregels:

MULTI_LINE_CODE_PLACEHOLDER_1

matchOptions in workbox-expiratie

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

precaching van werkvakken

Maakt gebruik van workbox-strategieën

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

Bij precaching worden de gegevens nu één voor één verwerkt, niet in bulk

workbox-precaching is bijgewerkt, zodat er slechts één item in het precache-manifest tegelijk wordt opgevraagd en in de cache opgeslagen, in plaats van te proberen ze allemaal tegelijk op te vragen en in de cache op te slaan (het aan de browser overlaten om uit te zoeken hoe dit moet worden beperkt).

Dit zou de waarschijnlijkheid van net::ERR_INSUFFICIENT_RESOURCES -fouten tijdens het precaching moeten verkleinen, en ook de bandbreedteconflicten tussen precaching en gelijktijdige verzoeken van de web-app moeten verminderen.

PrecacheFallbackPlugin zorgt voor eenvoudiger offline fallback

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

Dit maakt het eenvoudig om een ​​vooraf in de cache opgeslagen URL op te geven als 'fallback' voor een bepaalde strategie wanneer een antwoord anders niet beschikbaar zou zijn. De plug-in zorgt ervoor dat de juiste cachesleutel voor de vooraf in de cache opgeslagen URL correct wordt samengesteld, inclusief eventuele revisieparameters die nodig zijn.

Hier is een voorbeeld van het gebruik ervan om te reageren met een vooraf in de cache opgeslagen /offline.html wanneer de NetworkOnly -strategie geen antwoord kan genereren voor een navigatieverzoek, met andere woorden, het weergeven van een aangepaste offline HTML-pagina:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback in runtime-caching

Als u generateSW gebruikt om een ​​servicemedewerker voor u te maken in plaats van uw servicemedewerker met de hand te schrijven, kunt u de nieuwe precacheFallback configuratieoptie 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',
      },
    },
  }],
}

Hulp krijgen

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