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 deruntimeCaching
. 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 surruntimeCaching
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 optionsfollow: true
(qui suivront les liens symboliques) etstrict: 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éfinissantglobFollow: false
et/ouglobStrict: 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 viawarnings
, 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 dereturn manifestArray;
, vous devez utiliserreturn {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éegetManifest()
, 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ôtgetManifest()
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 queworkbox
. - Dans la version 2, les commandes
generate:sw
etinject:manifest
ont été renomméesgenerateSW
etinjectManifest
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 deworkbox-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 deprecacheAndRoute()
. - Plusieurs options qui étaient configurées via le constructeur
WorkboxSW
sont désormais transmises en tant que paramètreoptions
dansworkbox.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 dansworkbox.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 nomsworkbox.router.*
d'un objet WorkboxSW doivent passer au nouvel espace de nomsworkbox.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 valeurRoute
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 deworkbox-routing
. Les chaînes utilisées comme premier paramètre deworkbox.routing.registerRoute()
seront désormais traitées comme des correspondances exactes. Les correspondances génériques ou partielles doivent être gérées par desRegExp
. L'utilisation deRegExp
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 classeRouter
. Les développeurs peuvent soit ajouter leur propre gestionnairefetch
explicitement, soit utiliser l'interface fournie parworkbox.routing
, qui créera implicitement un gestionnairefetch
pour eux. - Suppression des méthodes
registerRoutes()
etunregisterRoutes()
. Les versions de ces méthodes qui opèrent sur un seulRoute
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()
ouunregisterRoute()
.
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 moduleworkbox-runtime-caching
a été publié surnpm
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éecachedResponseWillBeUsed
. 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 classeWorkboxSW
, 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
etclientsClaim
ne sont plus des options transmises au constructeurWorkboxSW
. Elles ont été remplacées par les méthodesworkbox.clientsClaim()
etworkbox.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.
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
etInjectManifest
. 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 deswSrc
. - 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 à utiliserglobPatterns
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 surglob
, 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.