Ce guide se concentre sur les modifications destructives introduites dans Workbox v4, avec des exemples des modifications que vous devrez apporter lors de la migration depuis Workbox v3.
Modifications majeures
workbox-precaching
La convention d'attribution de noms pour les entrées préchargées a été mise à jour. Désormais, pour les entrées dont les URL nécessitent des informations de gestion des versions (c'est-à-dire celles qui contiennent un champ revision dans le fichier manifeste de préchargement), ces informations de gestion des versions seront stockées dans la clé de cache, dans un paramètre de requête d'URL __WB_REVISION__ spécial ajouté à l'URL d'origine. (Auparavant, ces informations étaient stockées séparément des clés de cache, à l'aide d'IndexedDB.)
Les développeurs qui exploitent le précaut via workbox.precaching.precacheAndRoute(), qui est le cas d'utilisation le plus courant, n'ont pas besoin de modifier la configuration de leur service worker. Lorsque vous passez à Workbox v4, les éléments mis en cache de vos utilisateurs sont automatiquement migrés vers le nouveau format de clé de cache. À l'avenir, les ressources mises en cache continueront d'être diffusées de la même manière qu'auparavant.
Utiliser directement des clés de cache
Certains développeurs peuvent avoir besoin d'accéder directement aux entrées de préchargement, en dehors du contexte de workbox.precaching.precacheAndRoute(). Par exemple, vous pouvez pré-cacher une image que vous finirez par utiliser comme réponse de "recours" lorsqu'une image réelle ne peut pas être extraite du réseau.
Si vous utilisez des éléments pré-cachés de cette manière, à partir de la version 4 de Workbox, vous devrez effectuer une étape supplémentaire pour traduire une URL d'origine en clé de cache correspondante permettant de lire l'entrée mise en cache. Pour ce faire, appelez workbox.precaching.getCacheKeyForURL(originURL).
Par exemple, si vous savez que 'fallback.png' est mis en pré-cache:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Nettoyer les anciennes données préchargées
En raison des modifications apportées à la mise en cache préalable dans Workbox v4, les anciens mises en cache créées par des versions précédentes de Workbox ne sont pas compatibles. Par défaut, elles sont laissées telles quelles. Si vous passez de la version 3 de Workbox à la version 4, vous obtiendrez deux copies de toutes vos ressources préchargées.
Pour éviter cela, vous pouvez ajouter directement un appel à workbox.precaching.cleanupOutdatedCaches() à un service worker ou définir la nouvelle option cleanupOutdatedCaches: true si vous utilisez un outil de compilation en mode GenerateSW. La logique de nettoyage du cache fonctionne sur les conventions de dénomination des caches pour trouver les précaches plus anciens. Comme les développeurs ont la possibilité de remplacer ces conventions, nous avons opté pour la sécurité et n'avons pas activé cette fonctionnalité par défaut.
Nous invitons les développeurs qui rencontrent des problèmes lors de l'utilisation de cette fonctionnalité (par exemple, des faux positifs liés à la suppression) à nous en informer.
Capitalisation des paramètres
Deux paramètres facultatifs pouvant être transmis à workbox.precaching.precacheAndRoute() et workbox.precaching.addRoute() ont été renommés afin de normaliser notre convention de capitalisation globale. ignoreUrlParametersMatching est désormais ignoreURLParametersMatching, et cleanUrls est désormais cleanURLs.
workbox-strategies
Il existe deux façons à peu près équivalentes de créer une instance d'un gestionnaire dans workbox-strategies. Nous abandonnons la méthode fabrique au profit de l'appel explicite du constructeur de la stratégie.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
Bien que la syntaxe de la méthode de fabrique continuera de fonctionner dans la version 4, son utilisation générera un avertissement, et nous encourageons les développeurs à migrer avant la suppression de la prise en charge dans la prochaine version v5.
workbox-background-sync
La classe workbox.backgroundSync.Queue a été réécrite pour offrir aux développeurs plus de flexibilité et de contrôle sur la façon dont les requêtes sont ajoutées à la file d'attente et relues.
Dans la version 3, la classe Queue ne permettait d'ajouter des requêtes à la file d'attente que d'une seule manière (la méthode addRequest()), mais elle ne permettait pas de modifier la file d'attente ni de supprimer des requêtes.
Dans la version 4, la méthode addRequests() a été supprimée et les méthodes suivantes de type tableau ont été ajoutées:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Dans la version 3, la classe Queue acceptait également plusieurs rappels qui vous permettaient d'observer quand les requêtes étaient rejouées (requestWillEnqueue, requestWillReplay, queueDidReplay), mais la plupart des développeurs ont constaté qu'en plus de l'observation, ils souhaitaient contrôler la façon dont la file d'attente était rejouée, y compris la possibilité de modifier, de réorganiser ou même d'annuler dynamiquement des requêtes individuelles.
Dans la version 4, ces rappels ont été supprimés au profit d'un seul rappel onSync, qui est appelé chaque fois qu'une tentative de relecture est effectuée par le navigateur. Par défaut, le rappel onSync appelle replayRequests(), mais si vous avez besoin de mieux contrôler le processus de relecture, vous pouvez utiliser les méthodes de type tableau listées ci-dessus pour la relecture de la file d'attente comme vous le souhaitez.
Voici un exemple de logique de relecture personnalisée:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
De même, la classe workbox.backgroundSync.Plugin accepte les mêmes arguments que la classe Queue (puisqu'elle crée une instance Queue en interne). Elle a donc changé de la même manière.
workbox-expiration
Le package npm a été renommé workbox-expiration, conformément à la convention d'attribution de noms utilisée pour les autres modules. Ce package est fonctionnellement équivalent à l'ancien package workbox-cache-expiration, qui est désormais obsolète.
mise à jour-diffusion-boîte-de-travail
Le package npm a été renommé workbox-broadcast-update, conformément à la convention d'attribution de noms utilisée pour les autres modules. Ce package est fonctionnellement équivalent à l'ancien package workbox-broadcast-cache-update, qui est désormais obsolète.
Workbox-core
Dans Workbox v3, le niveau d'affichage des journaux pouvait être contrôlé via la méthode workbox.core.setLogLevel(), à laquelle vous transmettez l'une des valeurs de l'énumération workbox.core.LOG_LEVELS. Vous pouvez également lire le niveau de journalisation actuel via workbox.core.logLevel.
Toutes ces fonctionnalités ont été supprimées de Workbox v4, car tous les outils pour les développeurs modernes disposent désormais de fonctionnalités avancées de filtrage des journaux (voir Filtrer la sortie de la console pour les outils pour les développeurs Chrome).
workbox-sw
Deux méthodes qui étaient auparavant exposées directement dans l'espace de noms workbox (qui correspond au module workbox-sw) ont été déplacées vers workbox.core. workbox.skipWaiting() est devenu workbox.core.skipWaiting() et, de même, workbox.clientsClaim() est devenu workbox.core.clientsClaim().
Configuration de l'outil de compilation
Le nom de certaines options pouvant être transmises à "workbox-cli", "workbox-build" ou "workbox-webpack-plugin" a été modifié. Chaque fois que "Url" était utilisé dans un nom d'option, il a été remplacé par "URL". Par conséquent, les noms d'options suivants sont recommandés:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
La variante "Url" de ces noms d'options fonctionne toujours dans la version 4, mais génère un message d'avertissement. Nous encourageons les développeurs à effectuer la migration avant la sortie de la version 5.
Nouvelle fonctionnalité
workbox-window
Le nouveau module workbox-window simplifie le processus d'enregistrement du service worker et de détection des mises à jour. Il fournit un moyen de communication standard entre le code exécuté dans le service worker et le code exécuté dans le contexte window de votre application Web.
Bien que l'utilisation de workbox-window soit facultative, nous espérons que les développeurs la trouveront utile et qu'ils envisageront de migrer une partie de leur logique manuscrite pour l'utiliser le cas échéant. Pour en savoir plus sur l'utilisation de workbox-window, consultez le guide du module.
Exemple de migration
Vous trouverez un exemple de migration de la version 3 de Workbox vers la version 4 dans cette pull request.
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, veuillez nous le signaler sur GitHub.