Workbox

La gestion de votre service worker et de la logique de stockage du cache peut s'avérer compliquée à mesure que votre PWA prend de l'ampleur. Workbox est un ensemble de bibliothèques Open Source conçues pour vous aider dans cette tâche. Workbox encapsule les API de bas niveau, telles que l'API Service Worker et l'API Cache Storage, et expose des interfaces plus conviviales pour les développeurs.

Parmi les tâches qu'il peut vous aider, citons la mise en correspondance des stratégies de mise en cache avec les chemins (ou modèles de routage), l'utilisation de flux et l'utilisation de fonctionnalités telles que la synchronisation en arrière-plan avec des remplacements appropriés.

Workbox peut vous aider à gérer la mise en cache de vos éléments et vos besoins de diffusion. Il s'agit également de la bibliothèque la plus utilisée par les service workers. Elle est utilisée par 54% des sites mobiles, et elle est utilisée dans de nombreux outils de compilation et CLI, y compris la CLI Angular, Create-React-App et Vue CLI. Il existe également des plug-ins pour la plupart des autres bibliothèques et frameworks, comme Next.js.

54%

Les sites mobiles avec service workers utilisent la bibliothèque Workbox

Modules de la boîte de travail

Workbox comprend plusieurs bibliothèques, appelées modules, chacune étant axée sur un aspect différent de la gestion des éléments et du comportement du service worker.

Les modules de la boîte de travail fonctionnent dans différents contextes, par exemple:

  • Dans le contexte d'un service worker: vous importez les modules dont vous avez besoin et les utilisez à partir de votre fichier de service worker, par exemple pour gérer la mise en cache et diffuser les fichiers selon différentes stratégies.
  • Dans le contexte principal de window: aide à l'enregistrement d'un service worker et à la communication avec lui
  • Dans un système de compilation (webpack, par exemple) pour créer un fichier manifeste de vos éléments ou même générer l'ensemble de votre service worker.

Voici quelques modules populaires:

  • workbox-routing: lorsque le service worker intercepte des requêtes, ce module les achemine vers différentes fonctions qui fournissent des réponses. Il s'agit d'une implémentation du gestionnaire d'événements fetch, comme indiqué dans le chapitre Diffusion.
  • Workbox-strategies: ensemble de stratégies de mise en cache de l'environnement d'exécution qui gèrent la réponse à une requête (par exemple, la mise en cache d'abord et l'obsolescence lors de la revalidation). Il s'agit d'une implémentation des différentes stratégies mentionnées dans le chapitre Diffusion.
  • workbox-precaching: il s'agit d'une implémentation de la mise en cache des fichiers dans le gestionnaire d'événements install du service worker (également appelée "pré-mise en cache"), comme indiqué dans le chapitre Mise en cache. Grâce à ce module, vous pouvez facilement mettre en cache un ensemble de fichiers et gérer efficacement les mises à jour de ces éléments. Nous aborderons la mise à jour des assets dans le chapitre Mise à jour.
  • workbox-expiration: plug-in utilisé avec les stratégies de mise en cache pour supprimer les requêtes mises en cache en fonction du nombre d'éléments dans un cache ou de l'ancienneté de la requête mise en cache. Il facilite la gestion des caches et définit des limites de temps et de nombre d'éléments dans chaque cache.
  • workbox-window: ensemble de modules destinés à s'exécuter dans le contexte d'une fenêtre, c'est-à-dire au sein de vos pages Web PWA. Vous pouvez simplifier le processus d'enregistrement et de mise à jour d'un service worker, et faciliter la communication entre le code exécuté dans le contexte du service worker et le contexte de la fenêtre.

Utiliser Workbox

Workbox propose plusieurs méthodes d'intégration à votre PWA. Vous pouvez choisir celle qui convient le mieux à l'architecture de votre application:

  • CLI Workbox: utilitaire de ligne de commande qui génère un service worker complet, injecte un fichier manifeste en pré-cache ou copie les fichiers Workbox dont vous avez besoin.
  • Workbox Build: module npm qui génère un service worker complet, injecte un fichier manifeste de pré-cache et copie les fichiers Workbox. Elle est destinée à être intégrée à votre propre processus de compilation.
  • workbox-sw: moyen de charger les packages de service worker de Workbox à partir d'un CDN qui n'utilise pas de processus de compilation.

La CLI Workbox fournit un assistant qui vous guide tout au long de la création de votre service worker. Pour exécuter l'assistant, saisissez la commande suivante dans une ligne de commande:

npx workbox-cli wizard

CLI Workbox en action dans un terminal

Mise en cache et diffusion avec Workbox

Workbox est souvent utilisé en combinant les modules de routage et de stratégies pour mettre en cache et diffuser les fichiers.

Le module stratégies de boîte de travail fournit, par défaut, les stratégies de mise en cache abordées dans les chapitres Éléments et données et Diffusion.

Le module workbox-routing permet de trier les requêtes entrantes adressées à votre service worker et de les faire correspondre aux stratégies ou fonctions de mise en cache pour obtenir des réponses à ces requêtes.

Après la mise en correspondance des routes avec les stratégies, Workbox offre également la possibilité de filtrer les réponses qui seront ajoutées au cache avec le plug-in workbox-cacheable-response. Ce plug-in vous permet, par exemple, de mettre en cache uniquement les réponses renvoyées sans erreur.

L'exemple de code suivant utilise une stratégie de priorité à la mise en cache (via le module CacheFirst) pour mettre en cache et diffuser les navigations sur les pages.

import { registerRoute } from 'workbox-routing';
import { CacheFirst } from 'workbox-strategies';
import { CacheableResponsePlugin } from 'workbox-cacheable-response';

const pageStrategy = new CacheFirst({
  // Put all cached files in a cache named 'pages'
  cacheName: 'pages',
  plugins: [
    // Only requests that return with a 200 status are cached
    new CacheableResponsePlugin({
      statuses: [200],
    }),
  ],
});

Le plug-in vous permet d'exploiter le cycle de vie de mise en cache et de résolution des requêtes de Workbox. Ici, CacheableResponsePlugin est utilisé pour mettre en cache uniquement les requêtes dont l'état est 200, ce qui empêche l'enregistrement de requêtes incorrectes dans le cache.

Une fois la stratégie créée, il est temps d'enregistrer une route pour l'utiliser. L'exemple suivant appelle registerRoute(), en transmettant un objet Request à son rappel. Si request.mode est défini sur "navigate", il utilise la stratégie CacheFirst (appelée ici pageStrategy) définie dans l'exemple de code précédent.

// Cache page navigations (HTML) with a Cache First strategy
registerRoute( ({ request }) => request.mode === 'navigate',
  pageStrategy );

Lisez la documentation de Workbox pour découvrir d'autres exemples et bonnes pratiques.

Création de remplacement hors connexion

Le module workbox-routing possède également un setCatchHandler() exporté, qui permet de gérer si une route génère une erreur. Vous pouvez l'utiliser pour configurer une connexion hors connexion afin d'avertir les utilisateurs que l'itinéraire demandé n'est pas disponible actuellement.

Ici, une combinaison de Workbox et de l'API Cache Storage permet d'obtenir un remplacement hors connexion en utilisant une stratégie de mise en cache uniquement. Tout d'abord, pendant le cycle de vie d'installation du service worker, le cache offline-fallbacks est ouvert, et l'ensemble des solutions de remplacement hors connexion est ajouté au cache.

import { setCatchHandler } from 'workbox-routing';

// Warm the cache when the service worker installs
self.addEventListener('install', event => {
  const files = ['/offline.html']; // you can add more resources here
  event.waitUntil(
    self.caches.open('offline-fallbacks')
        .then(cache => cache.addAll(files))
  );
});

Ensuite, dans setCatchHandler(), la destination de la requête ayant généré une erreur est déterminée et le cache offline-fallbacks est ouvert. Si la destination est un document, le contenu de la création de remplacement hors connexion est renvoyé à l'utilisateur. Si ce n'est pas le cas ou si la destination n'est pas un document (comme une image ou une feuille de style), une erreur est renvoyée. Vous pouvez étendre ce modèle non seulement aux documents, mais également aux images, vidéos, polices et autres éléments que vous souhaitez fournir en remplacement hors connexion.

// Respond with the fallback if a route throws an error
setCatchHandler(async (options) => {
  const destination = options.request.destination;
  const cache = await self.caches.open('offline-fallbacks');
  if (destination === 'document') {
    return (await cache.match('/offline.html')) || Response.error();
  }
  return Response.error();
});

Recettes

Plusieurs modèles de routage et de mise en cache, tels que les navigations NetworkFirst et les remplacements hors connexion, sont suffisamment courants pour être encapsulés dans des recettes réutilisables. Cochez la case workbox-recipes, car elle peut vous aider s'il fournit une solution adaptée à votre architecture. Elles sont généralement disponibles sous la forme d'une seule ligne de code que vous devez ajouter au code de votre service worker.

Mettre en cache et mettre à jour des éléments

La mise en cache des éléments implique également leur mise à jour. Workbox vous aide à mettre à jour vos assets de la manière qui vous convient le mieux. Il peut s'agir de les maintenir à jour s'ils changent sur le serveur ou d'attendre une nouvelle version de votre application. Pour en savoir plus sur la mise à jour, consultez le chapitre Mise à jour.

Amusez-vous avec Workbox

Vous pouvez commencer à utiliser Workbox en suivant l'atelier de programmation suivant:

Ressources