zone de travail-prémise en cache

L'une des fonctionnalités des service workers est la possibilité d'enregistrer un ensemble de fichiers dans le cache lors de l'installation du service worker. Cette pratique est souvent appelée "pré-mise en cache", car vous mettez en cache le contenu avant l'utilisation du service worker.

Cela permet principalement aux développeurs de contrôler le cache, ce qui signifie qu'ils peuvent déterminer quand et pendant combien de temps un fichier est mis en cache, et le diffuser dans le navigateur sans passer par le réseau, ce qui signifie qu'il peut être utilisé pour créer des applications Web qui fonctionnent hors connexion.

Workbox simplifie considérablement la mise en cache en simplifiant l'API et en veillant à ce que les éléments soient téléchargés efficacement.

Fonctionnement de la pré-mise en cache de la boîte de travail

Lors du premier chargement d'une application Web, workbox-precaching examine tous les éléments que vous souhaitez télécharger, supprime les doublons et connecte les événements de service worker pertinents pour télécharger et stocker les éléments. Les URL qui comprennent déjà des informations de gestion des versions (comme un hachage de contenu) sont utilisées en tant que clés de cache sans aucune autre modification. La clé de cache des URL qui n'incluent pas d'informations de gestion des versions comporte un paramètre de requête supplémentaire. Celui-ci représente un hachage de leur contenu généré par Workbox au moment de la compilation.

workbox-precaching effectue toutes ces opérations lors de l'événement install du service worker.

Lorsqu'un utilisateur revient ultérieurement dans votre application Web et que vous avez un nouveau service worker avec différents éléments en pré-cache, workbox-precaching examine la nouvelle liste et détermine les éléments complètement nouveaux et ceux qui doivent être mis à jour, en fonction de leur révision. Tous les nouveaux éléments, ou les révisions mises à jour, sont ajoutés au cache lors de l'événement install du nouveau service worker.

Ce nouveau service worker ne sera pas utilisé pour répondre aux requêtes tant que son événement activate n'aura pas été déclenché. C'est dans l'événement activate que workbox-precaching recherche les éléments mis en cache qui ne figurent plus dans la liste des URL actuelles et les supprime du cache.

workbox-precaching effectue ces étapes chaque fois que votre service worker est installé et activé, afin de s'assurer que l'utilisateur dispose des derniers éléments et de ne télécharger que les fichiers qui ont été modifiés.

Diffuser des réponses mises en cache

L'appel de precacheAndRoute() ou addRoute() crée une route qui correspond aux requêtes d'URL en pré-cache.

La stratégie de réponse utilisée dans cette route est de type cache-first : la réponse en pré-cache sera utilisée, sauf si cette réponse mise en cache n'est pas présente (en raison d'une erreur inattendue), auquel cas une réponse du réseau sera utilisée à la place.

L'ordre dans lequel vous appelez precacheAndRoute() ou addRoute() est important. Vous devriez normalement l'appeler au début de votre fichier de service worker, avant d'enregistrer des routes supplémentaires avec registerRoute(). Si vous avez d'abord appelé registerRoute() et que cette route correspond à une requête entrante, la stratégie que vous avez définie dans cette route supplémentaire sera utilisée pour répondre, à la place de la stratégie de priorité au cache utilisée par workbox-precaching.

Explication de la liste de pré-cache

workbox-precaching attend un tableau d'objets avec les propriétés url et revision. Ce tableau est parfois appelé fichier manifeste de pré-cache:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Cette liste fait référence à un ensemble d'URL, chacune avec ses propres informations de "révision".

Pour les deuxième et troisième objets de l'exemple ci-dessus, la propriété revision est définie sur null. En effet, les informations de révision se trouvent dans l'URL elle-même, ce qui est généralement une bonne pratique pour les éléments statiques.

Le premier objet (/index.html) définit explicitement une propriété de révision, qui est un hachage généré automatiquement du contenu du fichier. Contrairement aux ressources JavaScript et CSS, les fichiers HTML ne peuvent généralement pas inclure d'informations de révision dans leurs URL, sinon les liens vers ces fichiers sur le Web seraient rompus à chaque modification du contenu de la page.

En transmettant une propriété de révision à precacheAndRoute(), Workbox peut savoir quand le fichier a été modifié et le mettre à jour en conséquence.

Workbox est fourni avec des outils permettant de générer cette liste:

• workbox-build: package de nœud qui peut être utilisé dans une tâche gulp ou en tant que script d'exécution npm.
• workbox-webpack-plugin: les utilisateurs de webpack peuvent utiliser ce plug-in.
• workbox-cli: notre CLI peut également être utilisée pour générer la liste des éléments et les ajouter à votre service worker.

Requêtes entrantes pour les fichiers en pré-cache

Une action prête à l'emploi de workbox-precaching consiste à manipuler les requêtes réseau entrantes pour essayer de faire correspondre les fichiers en pré-cache. Cela s'adapte aux pratiques courantes sur le Web.

Par exemple, une requête pour / peut généralement être satisfaite par le fichier dans /index.html.

Vous trouverez ci-dessous la liste des manipulations effectuées par défaut par workbox-precaching, ainsi que la manière dont vous pouvez modifier ce comportement.

Ignorer les paramètres d'URL

Les requêtes avec des paramètres de recherche peuvent être modifiées pour supprimer des valeurs spécifiques ou toutes les valeurs.

Par défaut, les paramètres de recherche qui commencent par utm_ ou correspondent exactement à fbclid sont supprimés, ce qui signifie qu'une requête pour /about.html?utm_campaign=abcd sera traitée avec une entrée en pré-cache pour /about.html.

Vous pouvez ignorer un autre ensemble de paramètres de recherche en utilisant ignoreURLParametersMatching:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Index de répertoire

Par défaut, les requêtes se terminant par / sont mises en correspondance avec les entrées auxquelles un index.html se termine. Cela signifie qu'une requête entrante pour / peut être automatiquement traitée avec l'entrée en pré-cache /index.html.

Vous pouvez modifier ce paramètre ou le désactiver complètement en définissant directoryIndex:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

URL propres

Si une requête ne correspond pas au précache, nous ajoutons .html à la fin pour prendre en charge les URL "propres" (c'est-à-dire les URL "jolies"). Cela signifie qu'une requête telle que /about sera traitée par l'entrée en pré-cache pour /about.html.

Vous pouvez désactiver ce comportement en définissant cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Manipulations personnalisées

Si vous souhaitez définir des correspondances personnalisées à partir des requêtes entrantes vers des éléments en pré-cache, vous pouvez le faire avec l'option urlManipulation. Il doit s'agir d'un rappel qui renvoie un tableau des correspondances possibles.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Utilisation avancée

Utiliser directement PrecacheController

Par défaut, workbox-precaching configure les écouteurs install et activate pour vous. Pour les développeurs familiarisés avec les service workers, cette approche n'est peut-être pas souhaitable s'ils ont besoin de plus de contrôle.

Au lieu d'utiliser l'exportation par défaut, vous pouvez utiliser directement PrecacheController pour ajouter des éléments au précache, déterminer quand ces éléments sont installés et quand le nettoyage doit être effectué.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Lire directement les éléments mis en cache

Il peut arriver que vous deviez lire directement un élément en pré-cache, en dehors du contexte du routage que workbox-precaching peut effectuer automatiquement. Par exemple, vous pouvez mettre en pré-cache des modèles HTML partiels qui doivent ensuite être récupérés et utilisés lors de la construction d'une réponse complète.

En général, vous pouvez utiliser l'API Cache Storage pour obtenir les objets Response mis en pré-cache, mais il y a une difficulté: la clé de cache d'URL à utiliser lors de l'appel de cache.match() peut contenir un paramètre de gestion des versions que workbox-precaching crée et gère automatiquement.

Pour obtenir la clé de cache appropriée, vous pouvez appeler getCacheKeyForURL() en transmettant l'URL d'origine, puis utiliser le résultat pour effectuer une cache.match() sur le cache approprié.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Si vous n'avez besoin que de l'objet Response en pré-cache, vous pouvez appeler matchPrecache(), qui utilisera automatiquement la clé de cache appropriée et effectuera une recherche dans le cache approprié:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Nettoyer les anciens précaches

La plupart des versions de Workbox conservent le même format pour le stockage des données en pré-cache. Les précaches créés par les anciennes versions de Workbox peuvent normalement être utilisés tels quels par les versions plus récentes. Cependant, il y a rarement une modification destructive du stockage de mise en cache préalable qui oblige les utilisateurs existants à tout télécharger à nouveau, ce qui rend les données précédemment mises en cache obsolètes. (Un tel changement s'est produit entre les versions de Workbox v3 et v4.)

Ces données obsolètes ne devraient pas interférer avec les opérations normales, mais elles contribuent à l'utilisation globale de votre quota de stockage et il peut être plus facile pour vos utilisateurs de les supprimer explicitement. Pour ce faire, ajoutez cleanupOutdatedCaches() à votre service worker ou définissez cleanupOutdatedCaches: true si vous utilisez l'un des outils de compilation de Workbox pour générer votre service worker.

Utiliser l'intégrité des sous-ressources

Certains développeurs peuvent souhaiter bénéficier des garanties supplémentaires offertes par l'application de l'intégrité des sous-ressources lors de la récupération d'URL en pré-cache sur le réseau.

Une propriété facultative supplémentaire appelée integrity peut être ajoutée à n'importe quelle entrée du fichier manifeste de pré-cache. Si elle est fournie, elle sera utilisée comme valeur integrity lors de la construction de la Request utilisée pour remplir le cache. En cas d'incohérence, le processus de mise en cache préalable échouera.

Déterminer quelles entrées de fichier manifeste en pré-cache doit avoir des propriétés integrity et déterminer les valeurs appropriées à utiliser n'entrent pas dans le cadre des outils de compilation de Workbox. Les développeurs qui souhaitent activer cette fonctionnalité doivent modifier le fichier manifeste de pré-cache généré par Workbox pour ajouter eux-mêmes les informations appropriées. L'option manifestTransform dans la configuration des outils de compilation de Workbox peut aider à:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)