Passer de la version 5 à la version 6 de Workbox

Ce guide se concentre sur les modifications destructives introduites dans Workbox v6, avec des exemples de modifications à apporter lors de la mise à niveau depuis Workbox v5.

Modifications destructives

workbox-core

La méthode skipWaiting() de workbox-core n'ajoute plus de gestionnaire install et équivaut à appeler simplement self.skipWaiting().

Utilisez désormais self.skipWaiting(), car skipWaiting() sera probablement supprimé dans Workbox v7.

workbox-precaching

• Les documents HTML interorigines 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 fbclid est désormais ignoré par workbox-precaching lors de la recherche d'une réponse pré-mise en cache pour une requête donnée.
• Le constructeur PrecacheController accepte désormais un objet avec des propriétés spécifiques comme paramètre, au lieu d'une chaîne. Cet objet accepte les propriétés suivantes : cacheName (qui remplit la même fonction que la chaîne transmise au constructeur dans la version 5), plugins (qui remplace la méthode addPlugins() de la version 5) et fallbackToNetwork (qui remplace l'option similaire transmise à createHandler() et à "createHandlerBoundToURL()" dans la version 5).
• Les méthodes install() et activate() de PrecacheController n'acceptent désormais qu'un seul paramètre, qui doit être défini respectivement sur un InstallEvent ou un ActivateEvent correspondant.
• La méthode addRoute() a été supprimée de PrecacheController. À la place, la nouvelle classe PrecacheRoute peut être utilisée pour créer une route que vous pouvez ensuite enregistrer.
• La méthode precacheAndRoute() a été supprimée de PrecacheController. (Elle existe toujours en tant que méthode d'assistance statique exportée par le module workbox-precaching.) Il a été supprimé, car PrecacheRoute peut être utilisé à la place.
• La méthode createMatchCalback() a été supprimée de PrecacheController. Vous pouvez utiliser le nouveau PrecacheRoute à la place.
• La méthode createHandler() a été supprimée de PrecacheController. La propriété strategy de l'objet PrecacheController peut être utilisée pour gérer les requêtes à la place.
• L'exportation statique createHandler() a déjà été supprimée du module workbox-precaching. À la place, les développeurs doivent créer une instance PrecacheController et utiliser sa propriété strategy.
• La route enregistrée avec precacheAndRoute() est désormais une "vraie" route qui utilise la classe Router de workbox-routing en arrière-plan. Cela peut entraîner un ordre d'évaluation différent de vos routes si vous entrelacez les appels à registerRoute() et precacheAndRoute().

workbox-routing

La méthode setDefaultHandler() accepte désormais un deuxième paramètre facultatif correspondant à la méthode HTTP à laquelle elle s'applique, par défaut 'GET'.

• Si vous utilisez setDefaultHandler() et que toutes vos requêtes sont GET, aucune modification n'est nécessaire.
• Si vous avez des requêtes qui ne sont pas GET (POST, PUT, etc.), setDefaultHandler() ne déclenchera plus de correspondance pour ces requêtes.

Configuration de compilation

L'option mode pour les modes getManifest et injectManifest dans workbox-build et workbox-cli n'était pas censé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 v10 ou une version ultérieure

Les versions de Node.js antérieures à la v10 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 à jour votre environnement d'exécution vers une version compatible.

Nouvelles améliorations

workbox-strategies

Workbox v6 introduit une nouvelle façon pour les développeurs tiers de définir leurs propres stratégies Workbox. Cela permet aux développeurs tiers d'étendre Workbox de manière à 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 prendre en charge cette fonctionnalité.

La classe de base Strategy est responsable de deux choses principales :

• Appeler des rappels de cycle de vie de plug-in communs à tous les gestionnaires de stratégie (par exemple, lorsqu'ils démarrent, répondent et se terminent).
• Créer une instance de "gestionnaire" capable de gérer l'état de chaque requête individuelle traitée par une stratégie.

Nouvelle classe "handler"

Auparavant, nous avions des modules internes appelant fetchWrapper et cacheWrapper, qui (comme leur nom l'indique) encapsulent les différentes API de récupération et de mise en 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 de gestionnaire, StrategyHandler, exposera ces méthodes afin que les stratégies personnalisées puissent appeler fetch() ou cacheMatch() et que tous 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, et qui "fonctionneraient" 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 unique pour cet objet de plug-in particulier et cet appel de stratégie particulier (c'est-à-dire l'appel à 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 de temps entre l'exécution de requestWillFetch et fetchDidSucceed ou fetchDidFail).

Nouveaux rappels de cycle de vie du plug-in

De nouveaux rappels de cycle de vie des plug-ins ont été ajoutés pour permettre aux développeurs d'exploiter pleinement 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éthode handle() de la stratégie ne renvoie une réponse. Ce rappel peut être utilisé pour modifier cette réponse avant de la renvoyer à un gestionnaire de routage ou à une autre logique personnalisée.
• handlerDidRespond : appelée après que la méthode handle() 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ée une fois que toutes les promesses de prolongation de la durée de vie ajoutées à l'événement à partir de l'appel de cette stratégie ont été réglées. Ce rappel peut être utilisé pour générer des rapports sur toutes les données qui doivent attendre que le gestionnaire ait terminé pour être calculées (par exemple, l'état de succès de cache, la latence du cache, la 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 en cas d'erreur réseau.

Les développeurs qui implémentent leurs propres stratégies personnalisées n'ont pas à se soucier d'appeler 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 de différentes 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 quelques améliorations :

• Il appelle postMessage() avec le corps du message standard de facto, {type: 'SKIP_WAITING'}, qu'un service worker généré par Workbox vérifie pour déclencher skipWaiting().
• Il choisit le bon service worker "en attente" auquel envoyer ce message, même s'il ne s'agit pas du même service worker que celui avec lequel workbox-window a été enregistré.

Suppression des événements "externes" au profit d'une propriété isExternal

Tous les événements "externes" dans workbox-window ont été supprimés et remplacés par des événements "normaux" avec une propriété isExternal définie sur true. Cela permet aux développeurs qui se soucient de la distinction de la détecter, et aux développeurs qui n'ont pas besoin de le savoir d'ignorer la propriété.

Recette plus propre "Proposer aux utilisateurs d'actualiser la page"

Grâce aux deux modifications ci-dessus, la recette "Proposer aux utilisateurs d'actualiser la page" peut être simplifiée :

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

workbox-routing

Un nouveau paramètre booléen, sameOrigin, est transmis à la fonction matchCallback utilisée dans workbox-routing. Elle est définie sur true si la requête concerne une URL de même origine, et sur "false" dans le cas contraire.

Cela simplifie certains codes standards courants :

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

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 destructives 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.

La mise en cache préalable traite désormais les entrées une par une, et non de manière groupée.

workbox-precaching a été mis à jour de sorte qu'une seule entrée du fichier manifeste de prémise en cache soit demandée et mise en cache à la fois, au lieu d'essayer de toutes les demander et de les mettre en cache en même temps (en laissant le navigateur déterminer comment limiter le débit).

Cela devrait réduire la probabilité d'erreurs net::ERR_INSUFFICIENT_RESOURCES lors de la mise en cache préalable, ainsi que la contention de bande passante entre la mise en cache préalable et les requêtes simultanées effectuées par l'application Web.

PrecacheFallbackPlugin facilite 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.

Cela permet de spécifier facilement une URL pré-mise en cache comme "solution de remplacement" pour une stratégie donnée lorsqu'une réponse n'est pas disponible. Le plug-in se chargera de construire correctement la clé de cache appropriée pour l'URL pré-mise en cache, y compris tout paramètre de révision nécessaire.

Voici un exemple d'utilisation pour répondre avec un /offline.html précaché lorsque la stratégie NetworkOnly ne peut pas générer de réponse pour une requête de navigation (en d'autres termes, afficher une page HTML hors connexion personnalisée) :

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback dans la mise en cache de l'environnement d'exécution

Si vous utilisez generateSW pour créer un service worker à votre place au lieu de l'écrire manuellement, 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

Nous pensons que la plupart des migrations seront simples. Si vous rencontrez des problèmes non abordés dans ce guide, veuillez nous en informer en signalant un problème sur GitHub.