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

Passer de Workbox v2 à v3

Ce guide est axé sur les modifications destructives introduites dans Workbox v3. Il fournit des exemples de modifications que vous devez apporter lorsque vous passez d'une configuration Workbox v2 à cette version.

Si vous utilisez actuellement l'ancienne combinaison sw-precache/sw-toolbox et que vous souhaitez passer à 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 objectifs principaux 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'inclure tous les utilisateurs dans un bundle monolithique, 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 proposons un service d'hébergement CDN entièrement compatible basé sur Google Cloud Storage. Il s'agit d'une option canonique pour accéder aux bibliothèques d'environnement d'exécution Workbox, ce qui facilite la prise en main de Workbox.
Débogage et journalisation améliorés 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 de webpack, ce qui permet un cas d'utilisation sans configuration lorsque vous souhaitez effectuer une mise en cache préalable de 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 provoquant des antimodèles, il a fallu apporter 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 et workbox-webpack-plugin), qui partagent un ensemble d'options de configuration communs.

Auparavant, le nom du gestionnaire 'fastest' était valide et était traité comme un alias pour 'staleWhileRevalidate' lors de la configuration de runtimeCaching. Elle n'est plus valide, et les développeurs doivent utiliser 'staleWhileRevalidate' directement.
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 d'une compilation si une configuration non valide est utilisée. Consultez la documentation sur runtimeCaching pour obtenir la liste des options actuellement compatibles.

boîte de travail-synchronisation-arrière-plan

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

workbox-broadcast-cache-update

Désormais, une chaîne obligatoire représentant le nom de la chaîne 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, initialisez la classe Plugin comme suit:

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

Voici l'utilisation équivalente dans la version 3:

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

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

création de boîte de travail

Par défaut, la mise en correspondance de format glob est désormais effectuée avec les options follow: true (qui suivront les liens symboliques) et strict: true (qui est moins tolérant aux erreurs "inhabituelles"). Vous pouvez désactiver l'un ou l'autre de ces éléments 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, 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 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};).mCela permet à votre plug-in d'inclure une propriété warnings facultative, qui devrait être un tableau de chaînes contenant des informations d'avertissement non fatales.

Si vous écrivez un ManifestTransform personnalisé en version 2, utilisez le code suivant:

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

dispose d'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 désormais des informations supplémentaires sur les URL mises en pré-cache.

Dans la version 2, le code se présente comme suit:

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

peuvent être réécrits dans la version 3 comme suit:

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 les données sur le disque au format approprié.

délai d'expiration du cache de la zone de travail

L'API du plug-in est restée la même, et c'est le mode que la plupart des développeurs utiliseront finalement. Toutefois, 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'option --help pour obtenir un ensemble complet de paramètres compatibles.

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

En résumé, cela signifie que dans la version 2:

$ workbox inject:manifest

exécute le processus de compilation "injecter un fichier manifeste" à l'aide d'une configuration lue à partir de workbox-cli-config.js, et dans la version 3:

$ workbox injectManifest

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

zone de travail-pré-cache

La méthode precache() procédait précédemment aux modifications du cache et à la configuration du 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 utiliser 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). Les valeurs par défaut de ces options, lorsqu'elles ne sont pas configurées, sont indiquées dans la documentation de référence.
Par défaut, les URL sans extension de fichier sont automatiquement recherchées afin de détecter une correspondance avec une entrée de cache comportant une extension .html. Par exemple, si une requête est effectuée pour /path/to/index (qui n'est pas en pré-cache) et qu'il existe une entrée en pré-cache pour /path/to/index.html, cette entrée en pré-cache sera 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([...]);

dispose d'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 dans lequel les utilisateurs se sont inscrits et ont gagné en premier. Il s'agit de l'ordre opposé de l'évaluation de la fonction Route utilisée dans la version 2. Dans ce cas, la dernière valeur Route enregistrée est prioritaire.
La classe ExpressRoute et les caractères génériques de type Express ont été supprimés. Cela permet de réduire 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 génériques ou partielles doivent être gérées par des RegExp. L'utilisation de RegExp qui correspond à tout ou partie de l'URL de la requête peut déclencher un routage.
Suppression de la méthode d'assistance addFetchListener() de la classe Router. Les développeurs peuvent soit ajouter leur propre gestionnaire fetch explicitement, soit utiliser l'interface fournie par workbox.routing, qui créera implicitement un gestionnaire fetch pour eux.
Suppression des méthodes registerRoutes() et unregisterRoutes(). Les versions de ces méthodes qui opèrent 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().

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

dispose d'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)

Reconnu officiellement sous le nom de workbox-strategies, le module workbox-runtime-caching a été publié sur npm sous son nouveau nom.
Utiliser l'expiration du cache dans une stratégie sans fournir de nom de cache n'est plus valide. Dans la version 2, c'était possible:

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

Cela entraînerait l'expiration des entrées dans le cache par défaut, ce qui est inattendu. Dans la version 3, vous devez indiquer un nom de cache:

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. Ce changement ne devrait pas être visible pour les développeurs, sauf s'ils ont écrit leurs propres plug-ins qui ont réagi à cacheWillMatch.
La syntaxe permettant de spécifier des plug-ins lors de la configuration d'une stratégie a changé. Chaque plug-in doit être explicitement listé 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],
  },
});

dispose d'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 le guide Utiliser des plug-ins.

boîte de travail-sw

En arrière-plan, workbox-sw a été réécrit pour devenir une interface de chargement légère, qui accepte une configuration de base et est chargée d'extraire les 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.

Auparavant dans la version 2:

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. Elles ont été remplacées par les méthodes workbox.clientsClaim() et workbox.skipWaiting().
L'option handleFetch précédemment prise en charge par le constructeur de la version 2 ne l'est plus dans la version 3. Les développeurs qui ont besoin de fonctionnalités similaires pour tester leur service worker sans appeler de gestionnaire de récupération 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.

plug-in-boîte-de-travail-webpack

Le plug-in a été sensiblement réécrit et peut, dans de nombreux cas, être utilisé en mode "zéro configuration". 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. Vous ne devez continuer à utiliser globPatterns que si vous devez effectuer une mise en cache préalable des éléments qui ne sont pas inclus dans votre build. En général, lorsque vous migrez vers le plug-in v3, vous devez commencer par supprimer l'intégralité de votre configuration précédente basée sur glob, puis l'ajouter à nouveau uniquement si vous en avez vraiment besoin.

Obtenir de l'aide

Nous estimons que la plupart des migrations seront simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, n'hésitez pas à nous le signaler sur GitHub.