Fonctionnement de Workbox

Workbox est suffisamment flexible pour s'adapter à quasiment n'importe quel processus de compilation de projet. Vous disposez ainsi de plusieurs façons d'utiliser Workbox, ce qui vous permet de choisir l'intégration la plus adaptée à votre projet. Quelle que soit la façon dont vous intégrez Workbox, les différents outils proposent une API similaire.

generateSW et injectManifest

Vous allez utiliser l'une des deux principales méthodes des outils de compilation de Workbox: generateSW ou injectManifest. La méthode à utiliser dépend du degré de flexibilité dont vous avez besoin. generateSW privilégie la facilité d'utilisation et la simplicité au détriment de la flexibilité. Vous pouvez ainsi déclarer un ensemble d'options de configuration et bénéficier en retour d'un service worker entièrement fonctionnel.

injectManifest offre une plus grande flexibilité, au détriment de la simplicité, car vous écrirez vous-même le code pour votre service worker, avec injectManifest fournissant un fichier manifeste en pré-cache pouvant être utilisé par les méthodes de mise en cache de Workbox.

Dans quel contexte utiliser generateSW ?

Vous devez utiliser generateSW dans les cas suivants:

  • Vous souhaitez mettre en pré-cache les fichiers associés à votre processus de compilation, y compris les fichiers dont les URL contiennent des valeurs de hachage que vous ne connaissez peut-être pas à l'avance.
  • Vous avez des besoins simples concernant la mise en cache de l'environnement d'exécution, qui peuvent être configurés via les options de generateSW.

Cas d'utilisation non valides de generateSW

En revanche, vous ne devez pas utiliser generateSW dans les cas suivants:

  • Vous souhaitez utiliser d'autres fonctionnalités de service worker (telles que Web Push).
  • Vous avez besoin de plus de flexibilité pour importer des scripts supplémentaires ou utiliser des modules Workbox spécifiques pour adapter votre service worker aux besoins de votre application.

Dans quel contexte utiliser injectManifest ?

Vous devez utiliser injectManifest dans les cas suivants:

  • Vous voulez mettre des fichiers en pré-cache, tout en écrivant votre propre service worker.
  • Vous avez des besoins complexes en matière de mise en cache ou de routage qui ne peuvent pas être exprimés via les options de configuration de generateSW.
  • Vous souhaitez utiliser d'autres API dans votre service worker (comme Web Push).

injectManifest diffère de generateSW dans la mesure où il nécessite que vous spécifiiez un fichier de service worker source. Dans ce workflow, le fichier de service worker source doit comporter une chaîne self.__WB_MANIFEST spéciale pour que injectManifest puisse le remplacer par le fichier manifeste de précache.

Cas d'utilisation non valides de injectManifest

Vous ne devez pas utiliser injectManifest dans les cas suivants:

  • Vous ne souhaitez pas utiliser la mise en cache préalable dans votre service worker.
  • Les exigences de nos service workers sont suffisamment simples pour être couvertes par ce que generateSW et ses options de configuration peuvent fournir.
  • Vous privilégiez la facilité d'utilisation à la flexibilité.

Utiliser les outils de compilation de Workbox

Si vous recherchez un moyen indépendant du framework d'utiliser Workbox dans votre processus de compilation, trois options s'offrent à vous:

  1. workbox-cli
  2. workbox-build.
  3. Utiliser un bundler (tel que workbox-webpack-plugin)

Chacun de ces outils de compilation propose les modes generateSW et injectManifest, avec un ensemble d'options similaire. Ce sont autant de choix judicieux lorsque vous ne souhaitez pas lier votre service worker alimenté par Workbox à un framework particulier. Afin de savoir laquelle de ces options est la plus adaptée, examinons rapidement chacune d'entre elles.

workbox-cli

Si vous cherchez le moyen le plus bas possible d'accéder à Workbox, la CLI est faite pour vous:

npm install workbox-cli --save-dev

Pour commencer à utiliser la CLI, exécutez l'assistant avec npx workbox wizard. L'assistant vous posera quelques questions, dont les réponses serviront à configurer un projet avec un fichier workbox-config.js que vous pourrez personnaliser selon vos besoins. La requête doit ressembler à ceci:

// A config for `generateSW`
export default {
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{css,woff2,png,svg,jpg,js}'
  ],
  swDest: 'dist/sw.js'
};

Une fois le fichier de configuration créé, la CLI peut exécuter les méthodes generateSW ou injectManifest pour vous. Le texte d'aide de la CLI contient plus d'informations et des exemples d'utilisation.

workbox-build

workbox-cli est un wrapper autour du module workbox-build. Vous pouvez aussi utiliser workbox-build directement. Lorsque vous utilisez workbox-build, au lieu de spécifier des options à l'aide d'un fichier workbox-config.js, vous utilisez les méthodes generateSW ou injectManifest directement dans un script de nœud, en transmettant un ensemble d'options similaire:

// build-sw.mjs
import {generateSW} from 'workbox-build';

generateSW({
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{css,woff2,png,svg,jpg,js}'
  ],
  swDest: 'dist/sw.js'
});

Dans l'exemple ci-dessus, workbox-build écrira le service worker généré dans le répertoire dist lorsque la commande node build-sw.mjs est exécutée.

Utiliser un bundler

Différents bundlers disposent de leurs propres plug-ins Workbox, mais le seul bundleur officiellement accepté par l'équipe Workbox est webpack, via workbox-webpack-plugin. Comme workbox-cli et workbox-build, workbox-webpack-plugin exécute les méthodes generateSW ou injectManifest, sauf que le plug-in met ces noms en majuscules comme GenerateSW ou InjectManifest. Sinon, l'utilisation est semblable à workbox-build:

// webpack.config.js
import {GenerateSW} from 'workbox-webpack-plugin';

export default {
  // Other webpack config options omitted for brevity...
  plugins: [
    new GenerateSW({
      swDest: './dist/sw.js'
    })
  ]
};

Les options que vous transmettez à GenerateSW ou InjectManifest ne sont pas identiques à generateSW ni à injectManifest, mais il existe un chevauchement important. En particulier, vous n'avez pas besoin de spécifier une option globDirectory pour GenerateSW, et vous ne pouvez pas spécifier d'option, car Webpack sait déjà où vos éléments de production sont regroupés.

Utiliser un framework

Tout ce qui a été abordé dans ce point se concentre sur l'utilisation de Workbox, quelles que soient les préférences de framework de l'utilisateur. Toutefois, il est possible d'utiliser Workbox dans un framework spécifique si cela facilite le développement. Par exemple, create-react-app est fourni par défaut avec Workbox. Les différentes intégrations de frameworks avec Workbox sont décrites dans un article ultérieur.

Notez que ces intégrations spécifiques au framework de Workbox peuvent limiter votre capacité à configurer Workbox comme vous le souhaitez. Dans de tels cas, vous pouvez toujours utiliser les méthodes décrites ici.

Que faire si je n'ai pas de processus de compilation ?

Ce document part du principe que votre projet comporte un processus de compilation, mais ce n'est peut-être pas le cas de votre projet. Si cela correspond à votre situation, vous pouvez toujours utiliser Workbox avec le module workbox-sw. Avec workbox-sw, vous pouvez charger l'environnement d'exécution Workbox à partir d'un CDN ou localement, et composer votre propre service worker.

Conclusion

La flexibilité de Workbox vous permet de l'utiliser dans presque tous les projets, quelles que soient ses préférences concernant le framework ou la chaîne d'outils. Toutes ces possibilités vous permettront d'effectuer la pré-mise en cache et la mise en cache de l'environnement d'exécution à l'aide de quelques méthodes, tout en offrant une plus grande flexibilité pour créer des service workers avec des fonctionnalités plus avancées en cas de besoin.