Workbox

La maintenance de votre service worker et de la logique de stockage en cache peut s'avérer difficile à mesure que votre PWA se développe. 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.

Il peut vous aider à faire correspondre des stratégies de mise en cache à des chemins (ou modèles de routage), à utiliser des flux et à utiliser des fonctionnalités telles que la synchronisation en arrière-plan avec des créations de remplacement appropriées.

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

54%

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

Modules de boîte de travail

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

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

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

Voici quelques-uns des modules les plus courants:

  • workbox-routing: lorsque le service worker intercepte des requêtes, ce module les achemine vers différentes fonctions fournissant 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 les réponses à une requête (par exemple, mise en cache en premier et non actualisée lors de la revalidation) il s'agit de l'implémentation des différentes stratégies mentionnées dans le chapitre Diffusion.
  • workbox-precaching: implémentation de la mise en cache des fichiers dans le gestionnaire d'événements install du service worker (également appelé précaching), comme indiqué dans le chapitre Mise en cache. Ce module vous permet de mettre en cache facilement un ensemble de fichiers et de gérer efficacement les mises à jour de ces éléments. Nous aborderons la mise à jour des éléments dans le chapitre "Mettre à 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 ces requêtes. Il facilite la gestion de vos 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 de fenêtre, c'est-à-dire à l'intérieur de vos pages Web PWA. Vous pouvez simplifier le processus d'enregistrement et de mise à jour des service workers, 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 différentes manières d'intégrer votre application à votre PWA. Vous pouvez choisir ce 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 de mise en cache préalable ou copie les fichiers Workbox nécessaires.
  • Workbox Build: module npm qui génère un service worker complet, injecte un fichier manifeste de pré-cache et copie les fichiers Workbox. Il est destiné à être intégré à votre propre processus de compilation.
  • workbox-sw: moyen de charger des packages de service workers pour Workbox à partir d'un CDN n'utilisant pas de processus de compilation.

La CLI Workbox fournit un assistant qui vous guide tout au long de la création d'un 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

Mettre en cache et diffuser avec Workbox

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

Le module workbox-strategies fournit directement les stratégies de mise en cache décrites 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 aux fonctions de mise en cache afin d'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 à ajouter au cache à l'aide du plug-in workbox-cacheable-response. Avec ce plug-in, vous pouvez, par exemple, mettre en cache uniquement les réponses renvoyées sans erreur.

L'exemple de code suivant utilise une stratégie "cache first" (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 la mise en cache et de la résolution des requêtes de Workbox. Ici, CacheableResponsePlugin est utilisé pour ne mettre en cache que les requêtes qui renvoient l'état 200, ce qui empêche l'enregistrement des 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 (ici appelée 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 );

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

Création hors connexion de remplacement

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

Ici, une combinaison de Workbox et de l'API Cache Storage permet d'obtenir une solution de secours hors connexion utilisant une stratégie "cache uniquement". Tout d'abord, pendant le cycle de vie de l'installation du service worker, le cache offline-fallbacks est ouvert, et le tableau des créations de remplacement hors connexion y est ajouté.

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 qui a 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 (une image ou une feuille de style, par exemple), une erreur est renvoyée. Vous pouvez étendre ce modèle non seulement aux documents, mais également aux images, vidéos, polices et tout ce 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 créations de remplacement hors connexion, sont suffisamment courants pour être encapsulés dans des recettes réutilisables. Consultez les recettes de la boîte de travail, car elles peuvent vous aider si elles proposent une solution adaptée à votre architecture. Elles sont généralement disponibles sous la forme d'une 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 de les mettre à jour. Workbox vous aide à mettre à jour vos éléments comme vous le souhaitez. Il peut s'agir de les maintenir à jour si elles changent sur le serveur, ou d'attendre d'avoir une nouvelle version de votre application. Pour en savoir plus sur la mise à jour, consultez le chapitre "Mettre à jour".

Jouer avec Workbox

Vous pouvez immédiatement commencer à utiliser Workbox à l'aide de l'atelier de programmation suivant:

Ressources