Ce guide se concentre sur les modifications destructives introduites dans Workbox v6, avec des exemples des modifications que vous devrez apporter lors de la mise à niveau à partir de Workbox v5.
Modifications majeures
workbox-core
La méthode skipWaiting() de workbox-core n'ajoute plus de gestionnaire install et équivaut à un simple appel de self.skipWaiting().
À partir de maintenant, utilisez plutôt self.skipWaiting(), car skipWaiting() sera probablement supprimé dans la version 7 de Workbox.
préparation de la boîte de travail
- Les documents HTML inter-origines pour les URL qui correspondent à une redirection HTTP ne peuvent plus être utilisés pour répondre à une requête de navigation avec
workbox-precaching. Ce scénario est généralement rare. - Le paramètre de requête d'URL
fbclidest désormais ignoré parworkbox-precachinglors de la recherche d'une réponse préchargée pour une requête donnée. - Le constructeur
PrecacheControllerutilise désormais un objet avec des propriétés spécifiques comme paramètre, au lieu d'une chaîne. Cet objet est compatible avec les propriétés suivantes:cacheName(qui sert au même objectif que la chaîne transmise au constructeur dans la version 5),plugins(qui remplace la méthodeaddPlugins()de la version 5) etfallbackToNetwork(qui remplace l'option similaire transmise àcreateHandler()et à "createHandlerBoundToURL()" dans la version 5). - Les méthodes
install()etactivate()dePrecacheControlleracceptent désormais exactement un paramètre, qui doit être défini sur unInstallEventou unActivateEventcorrespondant, respectivement. - La méthode
addRoute()a été supprimée dePrecacheController. À la place, la nouvelle classePrecacheRoutepeut être utilisée pour créer un parcours que vous pouvez ensuite enregistrer. - La méthode
precacheAndRoute()a été supprimée dePrecacheController. (Il existe toujours en tant que méthode d'assistance statique exportée par le moduleworkbox-precaching.) Il a été supprimé, carPrecacheRoutepeut être utilisé à la place. - La méthode
createMatchCalback()a été supprimée dePrecacheController. Vous pouvez utiliser le nouveauPrecacheRouteà la place. - La méthode
createHandler()a été supprimée dePrecacheController. La propriétéstrategyde l'objetPrecacheControllerpeut être utilisée pour gérer les requêtes à la place. - L'exportation statique
createHandler()a déjà été supprimée du moduleworkbox-precaching. À la place, les développeurs doivent construire une instancePrecacheControlleret utiliser sa propriétéstrategy. - Le parcours enregistré auprès de
precacheAndRoute()est désormais un parcours "réel" qui utilise la classeRouterdeworkbox-routingen arrière-plan. Cela peut entraîner un ordre d'évaluation différent de vos itinéraires si vous intercalez des appels àregisterRoute()etprecacheAndRoute().
workbox-routing
La méthode setDefaultHandler() accepte désormais un deuxième paramètre facultatif correspondant à la méthode HTTP à laquelle elle s'applique. La valeur par défaut est 'GET'.
- Si vous utilisez
setDefaultHandler()et que toutes vos requêtes sontGET, aucune modification n'est requise. - Si vous avez des demandes qui ne sont pas des
GET(POST,PUT, etc.),setDefaultHandler()ne fera plus correspondre ces requêtes.
Build Configuration (Configuration de compilation)
L'option mode pour les modes getManifest et injectManifest dans workbox-build et workbox-cli n'était pas destinée à être prise en charge et a été supprimée. Cela ne s'applique pas à workbox-webpack-plugin, qui est compatible avec mode dans son plug-in InjectManifest.
Les outils de compilation nécessitent Node.js 10 ou version ultérieure
Les versions de Node.js antérieures à la version 10 ne sont plus compatibles avec workbox-webpack-plugin, workbox-build ou workbox-cli. Si vous exécutez une version de Node.js antérieure à la version 8, mettez à niveau votre environnement d'exécution vers une version compatible.
Nouvelles améliorations
workbox-strategies
La version 6 de Workbox offre aux développeurs tiers une nouvelle façon de définir leurs propres stratégies Workbox. Cela permet aux développeurs tiers d'étendre Workbox afin de répondre pleinement à leurs besoins.
Nouvelle classe de base Strategy
Dans la version 6, toutes les classes de stratégie Workbox doivent étendre la nouvelle classe de base Strategy. Toutes les stratégies intégrées ont été réécrites pour accompagner ce changement.
La classe de base Strategy est responsable de deux éléments principaux:
- Invoquer des rappels de cycle de vie de plug-in communs à tous les gestionnaires de stratégie (par exemple, quand ils démarrent, répondent et se terminent)
- Créer une instance de "gestionnaire", qui peut gérer l'état de chaque requête individuelle gérée par une stratégie.
Nouvelle classe "handler"
Auparavant, les modules internes appellent fetchWrapper et cacheWrapper, qui (comme leur nom l'indique) encapsulent les différentes API d'extraction et de cache avec des hooks dans leur cycle de vie. C'est le mécanisme qui permet actuellement aux plug-ins de fonctionner, mais il n'est pas exposé aux développeurs.
La nouvelle classe "handler", StrategyHandler, exposera ces méthodes afin que les stratégies personnalisées puissent appeler fetch() ou cacheMatch() et que les plug-ins ajoutés à l'instance de stratégie soient automatiquement appelés.
Cette classe permettrait également aux développeurs d'ajouter leurs propres rappels de cycle de vie personnalisés qui pourraient être spécifiques à leurs stratégies. Ils fonctionneraient simplement avec l'interface de plug-in existante.
Nouvel état du cycle de vie du plug-in
Dans Workbox v5, les plug-ins sont sans état. Cela signifie que si une requête pour /index.html déclenche à la fois les rappels requestWillFetch et cachedResponseWillBeUsed, ces deux rappels n'ont aucun moyen de communiquer entre eux ni même de savoir qu'ils ont été déclenchés par la même requête.
Dans la version 6, tous les rappels de plug-in recevront également un nouvel objet state. Cet objet d'état sera propre à cet objet de plug-in particulier et à cet appel de stratégie particulier (c'est-à-dire l'appel de handle()). Cela permet aux développeurs d'écrire des plug-ins dans lesquels un rappel peut effectuer une action de manière conditionnelle en fonction de ce qu'un autre rappel du même plug-in a fait (par exemple, calculer le delta temporel entre l'exécution de requestWillFetch et de fetchDidSucceed ou fetchDidFail).
Nouveaux rappels de cycle de vie des plug-ins
De nouveaux rappels de cycle de vie des plug-ins ont été ajoutés pour permettre aux développeurs de tirer pleinement parti de l'état du cycle de vie des plug-ins:
handlerWillStart: appelé avant le début de l'exécution de toute logique de gestionnaire. Ce rappel peut être utilisé pour définir l'état initial du gestionnaire (par exemple, enregistrer l'heure de début).handlerWillRespond: appelé avant que la méthodehandle()des stratégies ne renvoie une réponse. Ce rappel peut être utilisé pour modifier cette réponse avant de la renvoyer à un gestionnaire de parcours ou à une autre logique personnalisée.handlerDidRespond: appelé après que la méthodehandle()de la stratégie a renvoyé une réponse. Ce rappel peut être utilisé pour enregistrer les détails de la réponse finale, par exemple après les modifications apportées par d'autres plug-ins.handlerDidComplete: appelé après que toutes les promesses de prolongation de durée de vie ajoutées à l'événement depuis l'appel de cette stratégie ont été traitées. Ce rappel peut être utilisé pour générer un rapport sur toutes les données qui doivent attendre que le gestionnaire ait terminé pour effectuer le calcul (par exemple, état de succès de cache, latence du cache, latence du réseau).handlerDidError: appelé si le gestionnaire n'a pas pu fournir de réponse valide à partir d'une source. Ce rappel peut être utilisé pour fournir un contenu de remplacement à la place d'une erreur réseau.
Les développeurs qui implémentent leurs propres stratégies personnalisées n'ont pas à s'inquiéter d'invoquer eux-mêmes ces rappels. Tout est géré par une nouvelle classe de base Strategy.
Types TypeScript plus précis pour les gestionnaires
Les définitions TypeScript pour diverses méthodes de rappel ont été normalisées. Cela devrait améliorer l'expérience des développeurs qui utilisent TypeScript et écrivent leur propre code pour implémenter ou appeler des gestionnaires.
workbox-window
Nouvelle méthode messageSkipWaiting()
Une nouvelle méthode, messageSkipWaiting(), a été ajoutée au module workbox-window pour simplifier le processus d'activation du service worker "en attente". Cela offre plusieurs avantages:
- Il appelle
postMessage()avec le corps de message standard de facto,{type: 'SKIP_WAITING'}, qu'un service worker généré par Workbox vérifie pour déclencherskipWaiting(). - Elle sélectionne le service worker "en attente" auquel envoyer ce message, même s'il ne s'agit pas du service worker avec lequel
workbox-windowa été enregistré.
Suppression des événements "externes" en faveur d'une propriété isExternal
Tous les événements "externes" de workbox-window ont été supprimés à la place des événements "normaux" avec une propriété isExternal définie sur true. Cela permet aux développeurs qui se soucient de cette distinction de la détecter, tandis que ceux qui n'ont pas besoin de la connaître peuvent ignorer la propriété.
Recette plus claire "Proposez aux utilisateurs de recharger la page"
Grâce aux deux modifications ci-dessus, la recette "Offrir un rechargement de page aux utilisateurs" peut être simplifiée:
MULTI_LINE_CODE_PLACEHOLDER_0
workbox-routing
Un nouveau paramètre booléen, sameOrigin, est transmis à la fonction matchCallback utilisée dans workbox-routing. Il est défini sur true si la requête concerne une URL de même origine, et sur "false" dans le cas contraire.
Cela simplifie certains éléments récurrents courants:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions dans workbox-expiration
Vous pouvez désormais définir matchOptions dans workbox-expiration, qui sera ensuite transmis en tant que CacheQueryOptions à l'appel cache.delete() sous-jacent. (La plupart des développeurs n'auront pas besoin de le faire.)
workbox-precaching
Utilise workbox-strategies
workbox-precaching a été réécrit pour utiliser workbox-strategies comme base. Cela ne devrait pas entraîner de modifications de rupture et devrait améliorer la cohérence à long terme de la façon dont les deux modules accèdent au réseau et au cache.
Le préchargement traite désormais les entrées une par une, et non de manière groupée.
workbox-precaching a été mis à jour afin qu'une seule entrée du fichier manifeste de préchargement soit demandée et mise en cache à la fois, au lieu d'essayer de les demander et de les mettre en cache toutes en même temps (laissant au navigateur le soin de déterminer comment limiter la bande passante).
Cela devrait réduire la probabilité d'erreurs net::ERR_INSUFFICIENT_RESOURCES lors du préchargement et réduire la contention de bande passante entre le préchargement et les requêtes simultanées effectuées par l'application Web.
PrecacheFallbackPlugin permet de faciliter le remplacement hors connexion
workbox-precaching inclut désormais un PrecacheFallbackPlugin, qui implémente la nouvelle méthode de cycle de vie handlerDidError ajoutée dans la version 6.
Vous pouvez ainsi facilement spécifier une URL prémise en cache comme "solution de secours" pour une stratégie donnée lorsqu'une réponse ne serait pas disponible. Le plug-in se chargera de créer correctement la clé de cache appropriée pour l'URL préchargée, y compris tout paramètre de révision nécessaire.
Voici un exemple d'utilisation de cette méthode pour répondre avec une /offline.html prémise en cache lorsque la stratégie NetworkOnly ne peut pas générer de réponse à une requête de navigation (en d'autres termes, pour afficher une page HTML hors connexion personnalisée) :
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback dans la mise en cache d'exécution
Si vous utilisez generateSW pour créer un service worker au lieu d'écrire manuellement le service, vous pouvez utiliser la nouvelle option de configuration precacheFallback dans runtimeCaching pour obtenir le même résultat:
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
Obtenir de l'aide
La plupart des migrations devraient être simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, veuillez nous en informer en créant un problème sur GitHub.