Migreer van Workbox v2 naar v3, Migreer van Workbox v2 naar v3

Deze handleiding is gericht op het doorbreken van de wijzigingen die in Workbox v3 zijn geïntroduceerd, met voorbeelden van de wijzigingen die u moet aanbrengen bij het upgraden van een Workbox v2-installatie.

Als u momenteel de verouderde combinatie sw-precache / sw-toolbox gebruikt en voor de eerste keer wilt overstappen naar Workbox, vindt u hier een andere migratiegids die u kan helpen.

v3 Achtergrond

De v3-release van Workbox vertegenwoordigt een aanzienlijke refactoring van de bestaande codebase. De overkoepelende doelstellingen zijn:

• Minimaliseer de grootte van de Workbox. De hoeveelheid runtimecode voor servicemedewerkers die wordt gedownload en uitgevoerd, is verminderd. In plaats van dat iedereen zich aanmeldt voor een monolithische bundel, wordt tijdens runtime alleen de code voor de specifieke functies die u gebruikt geïmporteerd.
• Workbox heeft een CDN. We bieden een volledig ondersteunde, op Google Cloud Storage gebaseerde CDN-hosting als de canonieke optie voor toegang tot de Workbox-runtimebibliotheken, waardoor het gemakkelijker wordt om met Workbox aan de slag te gaan.
• Betere foutopsporing en logboeken. De foutopsporings- en logboekervaring is enorm verbeterd. Foutopsporingslogboeken zijn standaard ingeschakeld wanneer Workbox wordt gebruikt vanuit een localhost oorsprong en alle logboekregistratie en beweringen worden verwijderd uit de productiebuilds.
• Verbeterde webpack-plug-in. workbox-webpack-plugin integreert nauwer met het webpack-buildproces, waardoor een zero-config-gebruiksscenario mogelijk is wanneer u alle assets in de build-pijplijn vooraf in de cache wilt plaatsen.

Om deze doelen te bereiken en enkele aspecten van de vorige interface op te ruimen die ongemakkelijk aanvoelden of tot antipatronen leidden, was het nodig een aantal belangrijke wijzigingen in de v3-release aan te brengen.

Veranderingen doorbreken

Configuratie bouwen

De volgende wijzigingen zijn van invloed op het gedrag van al onze buildtools ( workbox-build , workbox-cli , workbox-webpack-plugin ), die een gemeenschappelijke set configuratie-opties delen.

• De 'fastest' handlernaam was voorheen geldig en werd behandeld als een alias voor 'staleWhileRevalidate' bij het configureren van runtimeCaching . Het is niet langer geldig en ontwikkelaars moeten rechtstreeks overstappen op het gebruik van 'staleWhileRevalidate' .
• Verschillende eigenschapsnamen runtimeCaching.options zijn bijgewerkt en er is aanvullende parametervalidatie aanwezig die ervoor zorgt dat een build mislukt als een ongeldige configuratie wordt gebruikt. Zie de documentatie voor runtimeCaching voor een lijst met momenteel ondersteunde opties.

werkbox-achtergrondsynchronisatie

• De configuratieparameter maxRetentionTime wordt nu geïnterpreteerd als een aantal minuten in plaats van een aantal milliseconden.
• Er is nu een vereiste tekenreeks, die de wachtrijnaam vertegenwoordigt, die moet worden doorgegeven als de eerste parameter bij het construeren van de Plugin- of standalone-klasse. (Het werd eerder doorgegeven als een eigenschap van de opties.) Raadpleeg de documentatie voor het bijgewerkte API-oppervlak.

workbox-broadcast-cache-update

• Er is nu een vereiste string, die de kanaalnaam vertegenwoordigt, die moet worden doorgegeven als de eerste parameter bij het construeren van de Plugin- of standalone-klasse.

In v2 initialiseert u de klasse Plugin bijvoorbeeld als volgt:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

Het equivalente gebruik in v3 is:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Raadpleeg de documentatie voor het bijgewerkte API-oppervlak.

werkdoos-build

• Standaard wordt glob patroonmatching nu uitgevoerd met de opties follow: true (die volgt op symlinks) en strict: true (die minder tolerant is voor "ongebruikelijke" fouten). U kunt beide uitschakelen en terugkeren naar het vorige gedrag door globFollow: false en/of globStrict: false te stellen in uw buildconfiguratie.
• De functies in workbox-build retourneren allemaal een extra eigenschap, warnings , in de antwoorden die ze retourneren. Sommige scenario's die in v2 als fatale fouten werden behandeld, zijn nu toegestaan, maar worden gerapporteerd via warnings , wat een array van strings is.

In v2 zou je generateSW kunnen aanroepen zoals:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

Hoewel u dezelfde code in v3 kunt gebruiken, is het een goed idee om te controleren op eventuele warnings en deze te loggen:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));

• Ontwikkelaars die hun eigen aangepaste ManifestTransform functies in v2 hebben geschreven, moeten de manifest-array in een object retourneren (dat wil zeggen in plaats van return manifestArray; u moet return {manifest: manifestArray}; ) gebruiken.mHierdoor kan uw plug-in een optionele warnings opnemen, die moet een array van tekenreeksen zijn die niet-fatale waarschuwingsinformatie bevatten.

Als u een aangepaste ManifestTransform in v2 aan het schrijven was, codeer dan als volgt:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

heeft een v3-equivalent van:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

• De functie getFileManifestEntries() is hernoemd naar getManifest() , en de geretourneerde belofte bevat nu aanvullende informatie over de URL's die vooraf in de cache zijn opgeslagen.

Code zoals het volgende in v2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

kan in v3 worden herschreven als:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

• De functie generateFileManifest() is verwijderd. Ontwikkelaars worden aangemoedigd om in plaats daarvan getManifest() aan te roepen en het antwoord ervan te gebruiken om gegevens in het juiste formaat naar schijf te schrijven.

workbox-cache-vervaldatum

• De plug-in-API is hetzelfde gebleven, wat de modus is die de meeste ontwikkelaars uiteindelijk zullen gebruiken. Er zijn echter aanzienlijke API-wijzigingen die van invloed zijn op ontwikkelaars die het als een zelfstandige klasse gebruiken. Raadpleeg de documentatie voor het bijgewerkte API-oppervlak.

werkbox-cli

Ontwikkelaars kunnen de CLI uitvoeren met de vlag --help voor een volledige set ondersteunde parameters.

• Ondersteuning voor de workbox-cli alias voor het binaire script is verwijderd. Het binaire bestand is nu alleen toegankelijk als workbox .
• De v2-opdrachten generate:sw en inject:manifest zijn hernoemd naar generateSW en injectManifest in v3.
• In v2 werd aangenomen dat het standaardconfiguratiebestand (gebruikt als dit niet expliciet was opgegeven) workbox-cli-config.js in de huidige map was. In v3 is dit workbox-config.js .

Alles bij elkaar betekent dit dat in v2:

$ workbox inject:manifest

zou het buildproces "inject manifest" uitvoeren, met behulp van een configuratie die wordt gelezen uit workbox-cli-config.js en in v3:

$ workbox injectManifest

zal hetzelfde doen, maar lees de configuratie van workbox-config.js .

precaching van werkvakken

• De methode precache() voerde eerder zowel de cachewijzigingen uit als de routering om in de cache opgeslagen vermeldingen te verwerken. Nu wijzigt precache() alleen cache-items, en een nieuwe methode, addRoute() , is beschikbaar om een ​​route te registreren om die in de cache opgeslagen antwoorden te bedienen. Ontwikkelaars die de vorige twee-in-één-functionaliteit willen, kunnen overschakelen naar het aanroepen precacheAndRoute() .
• Verschillende opties die vroeger via de WorkboxSW constructor werden geconfigureerd, worden nu doorgegeven als de options in workbox.precaching.precacheAndRoute([...], options) . De standaardinstellingen voor deze opties worden, als ze niet zijn geconfigureerd, vermeld in de referentiedocumenten .
• Standaard worden URL's zonder bestandsextensie automatisch gecontroleerd op een overeenkomst met een cache-item met een .html extensie. Als er bijvoorbeeld een verzoek wordt gedaan voor /path/to/index (die niet vooraf in de cache is geplaatst) en er is een vooraf in de cache opgeslagen vermelding voor /path/to/index.html , zal die vooraf in de cache opgeslagen vermelding worden gebruikt. Ontwikkelaars kunnen dit nieuwe gedrag uitschakelen door {cleanUrls: false} in te stellen bij het doorgeven van opties aan workbox.precaching.precacheAndRoute() .
• workbox-broadcast-update wordt niet langer automatisch geconfigureerd om cache-updates voor vooraf in de cache opgeslagen assets aan te kondigen.

De volgende code in v2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

heeft een v3-equivalent van:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

werkdoos-routing

• Ontwikkelaars die eerder workbox-routing gebruikten via de workbox.router.* naamruimte van een WorkboxSW-object moeten overschakelen naar de nieuwe naamruimte, workbox.routing.* .
• Routes worden nu geëvalueerd in de volgorde van de eerste geregistreerde overwinningen. Dit is de tegenovergestelde volgorde van Route evaluatie die werd gebruikt in v2, waarbij de laatst geregistreerde Route voorrang zou krijgen.
• De ExpressRoute klasse en ondersteuning voor jokertekens in 'Express-stijl' zijn verwijderd . Dit vermindert de omvang van workbox-routing aanzienlijk. Tekenreeksen die als eerste parameter voor workbox.routing.registerRoute() worden gebruikt, worden nu behandeld als exacte overeenkomsten. Wildcard- of gedeeltelijke overeenkomsten moeten worden afgehandeld door RegExp 's. Het gebruik van elke RegExp die overeenkomt met een deel of de gehele aanvraag-URL kan een route activeren.
• De helpermethode addFetchListener() van de klasse Router is verwijderd. Ontwikkelaars kunnen expliciet hun eigen fetch handler toevoegen, of de interface van workbox.routing gebruiken, die impliciet een fetch handler voor hen zal creëren.
• De methoden registerRoutes() en unregisterRoutes() zijn verwijderd. De versies van de methoden die op één Route werken, zijn niet gewijzigd, en ontwikkelaars die meerdere routes tegelijk moeten registreren of de registratie ongedaan moeten maken, moeten in plaats daarvan een reeks aanroepen doen naar registerRoute() of unregisterRoute() .

De volgende code in v2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

heeft een v3-equivalent van:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

workbox-strategieën (voorheen bekend als workbox-runtime-caching)

• De workbox-runtime-caching module staat nu officieel bekend als workbox-strategies en is onder de nieuwe naam op npm gepubliceerd .
• Het gebruik van cachevervaldatum in een strategie zonder ook een cachenaam op te geven, is niet langer geldig. In v2 was dit mogelijk:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Dit zou ertoe leiden dat vermeldingen in de standaardcache vervallen, wat onverwacht is. In v3 is een cachenaam vereist:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

• De cacheWillMatch levenscyclusmethode is hernoemd naar cachedResponseWillBeUsed . Dit zou voor ontwikkelaars geen zichtbare verandering moeten zijn, tenzij ze hun eigen plug-ins schreven die reageerden op cacheWillMatch .
• De syntaxis voor het opgeven van plug-ins bij het configureren van een strategie is gewijzigd. Elke plug-in moet expliciet worden vermeld in de plugins eigenschap van de configuratie van de strategie.

De volgende code in v2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

heeft een v3-equivalent van:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Meer informatie vindt u in de handleiding ' Plug-ins gebruiken '.

werkkast-sw

• Onder de motorkap is workbox-sw herschreven tot een lichtgewicht "loader"-interface, die enige basisconfiguratie vereist en verantwoordelijk is voor het binnenhalen van de andere modules die nodig zijn tijdens runtime. In plaats van een nieuw exemplaar van de WorkboxSW klasse te construeren, zullen ontwikkelaars communiceren met een bestaand exemplaar dat automatisch wordt weergegeven in de globale naamruimte.

Eerder in v2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

In v3 hoeft u alleen maar het workbox-sw.js script te importeren en een kant-en-klare instantie zal automatisch beschikbaar zijn in de globale naamruimte als workbox :

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

• skipWaiting en clientsClaim zijn niet langer opties die worden doorgegeven aan de WorkboxSW constructor. In plaats daarvan zijn ze gewijzigd in de methoden workbox.clientsClaim() en workbox.skipWaiting() .
• De handleFetch optie die eerder werd ondersteund in de v2-constructor, wordt niet langer ondersteund in v3. Ontwikkelaars die vergelijkbare functionaliteit nodig hebben om hun servicemedewerker te testen zonder dat er ophaalhandlers worden aangeroepen, kunnen de optie ' Omzeilen voor netwerk ' gebruiken die beschikbaar is in de ontwikkelaarstools van Chrome.

workbox-webpack-plug-in

De plug-in is substantieel herschreven en kan in veel gevallen worden gebruikt in een "zero-configuratie" -modus. Raadpleeg de documentatie voor het bijgewerkte API-oppervlak.

• De API biedt nu twee klassen, GenerateSW en InjectManifest . Dit maakt het schakelen tussen modi expliciet, vergeleken met het v2-gedrag waarbij het gedrag veranderde op basis van de aanwezigheid van swSrc .
• Standaard worden assets in de webpack-compilatiepijplijn vooraf in de cache geplaatst en is het niet langer nodig om globPatterns te configureren. De enige reden om globPatterns te blijven gebruiken is als u assets vooraf in de cache moet opslaan die niet zijn opgenomen in uw webpack-build. Over het algemeen moet u bij het migreren naar de v3-plug-in beginnen met het verwijderen van al uw eerdere, glob gebaseerde configuratie, en deze alleen opnieuw toevoegen als u deze specifiek nodig heeft.

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 .