Cette page a été traduite par l'API Cloud Translation.

Passer de Workbox v2 à v3

Ce guide présente les modifications destructives introduites dans Workbox v3 et fournit des exemples de modifications à apporter lorsque vous effectuez la mise à niveau à partir d'une configuration Workbox v2.

Si vous utilisez actuellement l'ancienne combinaison sw-precache/sw-toolbox et que vous souhaitez effectuer la transition vers Workbox pour la première fois, voici un autre guide de migration qui vous sera utile.

Arrière-plan v3

La version 3 de Workbox représente une refactorisation importante du codebase existant. Les principaux objectifs sont les suivants:

Réduisez la taille de la boîte de travail. La quantité de code d'exécution de service worker téléchargée et exécutée a été réduite. Au lieu d'activer un bundle monolithique pour tous les utilisateurs, seul le code des fonctionnalités spécifiques que vous utilisez sera importé au moment de l'exécution.
Workbox dispose d'un CDN. Nous fournissons un hébergement CDN basé sur Google Cloud Storage entièrement compatible, qui constitue l'option canonique pour accéder aux bibliothèques d'exécution Workbox, ce qui facilite la prise en main de Workbox.
Amélioration du débogage et des journaux. L'expérience de débogage et de journalisation a été considérablement améliorée. Les journaux de débogage sont activés par défaut chaque fois que Workbox est utilisé à partir d'une origine localhost et que toutes les journaux et assertions sont supprimés des builds de production.
Amélioration du plug-in webpack. workbox-webpack-plugin s'intègre plus étroitement au processus de compilation webpack, ce qui permet un cas d'utilisation sans configuration lorsque vous souhaitez mettre en pré-cache tous les éléments du pipeline de compilation.

Pour atteindre ces objectifs et nettoyer certains aspects de l'interface précédente qui semblaient gênants ou qui entraînaient des antimodèles, il a fallu introduire un certain nombre de modifications destructives dans la version 3.

Modifications majeures

Build Configuration (Configuration de compilation)

Les modifications suivantes affectent le comportement de tous nos outils de compilation (workbox-build, workbox-cli, workbox-webpack-plugin), qui partagent un ensemble commun d'options de configuration.

Le nom du gestionnaire 'fastest' était auparavant valide et traité comme un alias pour 'staleWhileRevalidate' lors de la configuration de runtimeCaching. Il n'est plus valide, et les développeurs doivent passer directement à 'staleWhileRevalidate'.
Plusieurs noms de propriétés runtimeCaching.options ont été mis à jour, et une validation supplémentaire des paramètres est en place, ce qui entraîne l'échec de la compilation si une configuration non valide est utilisée. Consultez la documentation sur runtimeCaching pour obtenir la liste des options actuellement compatibles.

workbox-background-sync

Le paramètre de configuration maxRetentionTime est maintenant interprété comme un nombre de minutes, et non comme un nombre de millisecondes.
Il existe désormais une chaîne obligatoire, représentant le nom de la file d'attente, qui doit être transmise en tant que premier paramètre lors de la création du plug-in ou de la classe autonome. (Il a déjà été transmis en tant que propriété des options.) Consultez la documentation pour connaître la surface d'API mise à jour.

workbox-broadcast-cache-update

Il existe désormais une chaîne obligatoire, représentant le nom du canal, qui doit être transmise en tant que premier paramètre lors de la création du plug-in ou de la classe autonome.

Par exemple, dans la version 2, vous initialisez la classe Plugin comme suit:

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

L'utilisation équivalente dans la version 3 est la suivante:

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

Consultez la documentation pour connaître la surface d'API mise à jour.

workbox-build

Par défaut, la mise en correspondance des formats glob sera désormais effectuée avec les options follow: true (qui suivront les liens symboliques) et strict: true (qui est moins tolérante aux erreurs "inhabituelles"). Vous pouvez désactiver l'une ou l'autre de ces options et revenir au comportement précédent en définissant globFollow: false et/ou globStrict: false dans votre configuration de compilation.
Les fonctions de workbox-build renvoient toutes une propriété supplémentaire, warnings, dans les réponses qu'elles renvoient. Certains scénarios traités comme des erreurs fatales dans la version 2 sont désormais autorisés, mais signalés via warnings, qui est un tableau de chaînes.

Dans la version 2, vous pourriez appeler generateSW comme suit:

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}`));

Bien que vous puissiez utiliser le même code dans la version 3, il est recommandé de rechercher les éventuels warnings et de les enregistrer:

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}`));

Les développeurs qui ont écrit leurs propres fonctions ManifestTransform personnalisées dans la version 2 doivent renvoyer le tableau du fichier manifeste dans un objet (par exemple, au lieu de return manifestArray;, vous devez utiliser return {manifest: manifestArray};). Votre plug-in peut ainsi inclure une propriété warnings facultative, qui doit être un tableau de chaînes contenant des avertissements non fatals.

Si vous écriviez un ManifestTransform personnalisé dans la version 2, le code se présente comme suit:

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

possède un équivalent v3 de:

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: []};
};

La fonction getFileManifestEntries() a été renommée getManifest(), et la promesse renvoyée inclut des informations supplémentaires sur les URL mises en pré-cache.

Code semblable à ce qui suit dans la version 2:

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

peut être réécrit comme suit dans la version 3:

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

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

La fonction generateFileManifest() a été supprimée. Nous encourageons les développeurs à appeler plutôt getManifest() et à utiliser sa réponse pour écrire des données sur le disque dans le format approprié.

workbox-cache-expiration

L'API du plug-in est restée la même, et c'est le mode que la plupart des développeurs vont utiliser. Cependant, des modifications importantes de l'API ont un impact sur les développeurs qui l'utilisent en tant que classe autonome. Consultez la documentation pour connaître la surface d'API mise à jour.

workbox-cli

Les développeurs peuvent exécuter la CLI avec l'indicateur --help pour obtenir un ensemble complet de paramètres compatibles.

L'alias workbox-cli pour le script binaire n'est plus pris en charge. Le binaire n'est désormais accessible qu'en tant que workbox.
Les commandes generate:sw et inject:manifest de la version 2 ont été renommées generateSW et injectManifest dans la version 3.
Dans la version 2, le fichier de configuration par défaut (utilisé lorsqu'il n'était pas explicitement fourni) était workbox-cli-config.js dans le répertoire actuel. Dans la version 3, il s'agit de workbox-config.js.

Au total, cela signifie que dans la version 2:

$ workbox inject:manifest

exécuterait la commande « injecter le fichier manifeste » à l'aide d'une configuration lue à partir de workbox-cli-config.js et dans la version 3:

$ workbox injectManifest

fera de même, mais lit la configuration à partir de workbox-config.js.

préparation de la boîte de travail

Auparavant, la méthode precache() permettait d'effectuer les modifications du cache et de configurer le routage pour diffuser les entrées mises en cache. Désormais, precache() ne modifie que les entrées de cache, et une nouvelle méthode, addRoute(), a été exposée pour enregistrer une route permettant de diffuser ces réponses mises en cache. Les développeurs qui souhaitent bénéficier de l'ancienne fonctionnalité deux en un peuvent passer à l'appel de precacheAndRoute().
Plusieurs options qui étaient configurées via le constructeur WorkboxSW sont désormais transmises en tant que paramètre options dans workbox.precaching.precacheAndRoute([...], options). Lorsqu'elles ne sont pas configurées, les valeurs par défaut de ces options sont indiquées dans la documentation de référence.
Par défaut, nous vérifions automatiquement si les URL sans extension de fichier correspondent à une entrée de cache comportant l'extension .html. Par exemple, si une requête est envoyée pour /path/to/index (qui n'est pas mise en pré-cache) et qu'il existe une entrée en pré-cache pour /path/to/index.html, cette entrée est utilisée. Les développeurs peuvent désactiver ce nouveau comportement en définissant {cleanUrls: false} lors de la transmission d'options dans workbox.precaching.precacheAndRoute().
workbox-broadcast-update ne sera plus configuré automatiquement pour annoncer les mises à jour du cache pour les éléments mis en pré-cache.

Le code suivant dans la version 2:

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

possède un équivalent v3 de:

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

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

routage de la boîte de travail

Les développeurs qui utilisaient précédemment workbox-routing via l'espace de noms workbox.router.* d'un objet WorkboxSW doivent passer au nouvel espace de noms, workbox.routing.*.
Les routes sont désormais évaluées selon l'ordre des gagnants enregistrés. Il s'agit de l'ordre opposé d'évaluation des Route utilisé dans la version 2, où le dernier Route enregistré serait prioritaire.
La classe ExpressRoute et la compatibilité avec le style Express caractères génériques ont été supprimés. Cela réduit considérablement la taille de workbox-routing. Les chaînes utilisées comme premier paramètre de workbox.routing.registerRoute() seront désormais traitées comme des correspondances exactes. Les correspondances partielles ou génériques avec des caractères génériques doivent être gérées par les RegExp. L'utilisation de toute RegExp correspondant à une partie ou à la totalité de l'URL de requête peut déclencher un routage.
La méthode d'assistance addFetchListener() de la classe Router a été supprimée. Les développeurs peuvent soit ajouter explicitement leur propre gestionnaire fetch, soit utiliser l'interface fournie par workbox.routing, qui créera implicitement un gestionnaire fetch pour eux.
Les méthodes registerRoutes() et unregisterRoutes() ont été supprimées. Les versions de ces méthodes qui fonctionnent sur un seul Route n'ont pas été modifiées, et les développeurs qui doivent enregistrer ou annuler l'enregistrement de plusieurs routes à la fois doivent effectuer une série d'appels à registerRoute() ou unregisterRoute() à la place.

Le code suivant dans la version 2:

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()
);

possède un équivalent v3 de:

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

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

Workbox-strategies (anciennement "workbox-runtime-caching")

Le module workbox-runtime-caching est désormais officiellement appelé workbox-strategies, et a été publié sur npm sous son nouveau nom.
L'utilisation de l'expiration du cache dans une stratégie sans fournir également de nom de cache n'est plus valide. C'était possible dans la version 2:

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

Cela entraînerait l'expiration d'entrées dans le cache par défaut, ce qui est inattendu. Dans la v3, un nom de cache est obligatoire:

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

La méthode de cycle de vie cacheWillMatch a été renommée cachedResponseWillBeUsed. Cela ne devrait pas être un changement visible pour les développeurs, sauf s'ils ont écrit leurs propres plug-ins qui ont réagi à cacheWillMatch.
La syntaxe de spécification des plug-ins lors de la configuration d'une stratégie a changé. Chaque plug-in doit être explicitement répertorié dans la propriété plugins de la configuration de la stratégie.

Le code suivant dans la version 2:

const workboxSW = new self.WorkboxSW();

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

possède un équivalent v3 de:

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

Pour en savoir plus, consultez l'article Utiliser des plug-ins. .

travail-box-sw

En arrière-plan, workbox-sw a été réécrit pour devenir un "chargeur" léger. , qui nécessite une configuration de base et qui est responsable de l'extraction des autres modules nécessaires au moment de l'exécution. Au lieu de construire une nouvelle instance de la classe WorkboxSW, les développeurs interagiront avec une instance existante qui est automatiquement exposée dans l'espace de noms global.

Précédemment dans la 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(...);

Dans la version 3, il vous suffit d'importer le script workbox-sw.js pour qu'une instance prête à l'emploi soit automatiquement disponible dans l'espace de noms global en tant que workbox:

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

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

skipWaiting et clientsClaim ne sont plus des options transmises au constructeur WorkboxSW. À la place, elles ont été remplacées par les méthodes workbox.clientsClaim() et workbox.skipWaiting().
L'option handleFetch qui était auparavant compatible avec le constructeur de la version 2 n'est plus prise en charge dans la version 3. Les développeurs qui ont besoin de fonctionnalités similaires pour tester leur service worker sans qu'aucun gestionnaire d'extraction ne soit appelé peuvent utiliser l'option Ignorer pour le réseau. disponible dans les outils pour les développeurs Chrome.

Option "Ignorer pour le réseau" dans les outils pour les développeurs Chrome.

workbox-webpack-plugin

Le plug-in a été considérablement réécrit et, dans de nombreux cas, il peut être utilisé dans une "configuration nulle" . Consultez la documentation pour connaître la surface d'API mise à jour.

L'API expose désormais deux classes, GenerateSW et InjectManifest. Le passage d'un mode à l'autre est donc explicite, contrairement au comportement de la version 2 où le comportement a changé en fonction de la présence de swSrc.
Par défaut, les éléments du pipeline de compilation webpack sont mis en pré-cache, et il n'est plus nécessaire de configurer globPatterns. La seule raison de continuer à utiliser globPatterns est de mettre en pré-cache des éléments qui ne sont pas inclus dans votre build webpack. En règle générale, lorsque vous migrez vers le plug-in v3, vous devez commencer par supprimer toute votre configuration précédente basée sur glob, puis l'ajouter à nouveau uniquement si vous en avez besoin spécifiquement.

Obtenir de l'aide

Selon nous, la plupart des migrations sont simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, signalez-les sur GitHub.