Fonctionnement de Workbox

Workbox est suffisamment flexible pour s'adapter à quasiment tous les processus de compilation de projets. Cela signifie qu'il existe plusieurs façons d'utiliser Workbox, ce qui vous permet de choisir la bonne intégration pour 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 utiliserez l'une des deux principales méthodes d'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é, ce qui vous permet de déclarer un ensemble d'options de configuration et d'obtenir en retour un service worker entièrement fonctionnel.

injectManifest offre une plus grande flexibilité au prix d'une certaine simplicité, car vous finirez par écrire vous-même le code pour votre service worker, et injectManifest fournit un fichier manifeste de mise en cache qui peut ê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 hachages que vous ne connaissez peut-être pas à l'avance.
  • Vous avez des besoins simples de mise en cache de l'environnement d'exécution qui peuvent être configurés via les options de generateSW.

Quand ne pas utiliser generateSW

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

  • Vous souhaitez utiliser d'autres fonctionnalités de service workers (telles que Web Push).
  • Vous avez besoin d'une plus grande 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 en pré-cache des fichiers tout en écrivant votre propre service worker.
  • Vous avez des besoins complexes 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 (telles que Web Push).

injectManifest diffère de generateSW en ce sens qu'il nécessite que vous spécifiiez un fichier de service worker source. Dans ce workflow, le fichier de service worker source doit contenir une chaîne self.__WB_MANIFEST spéciale pour que injectManifest puisse le remplacer par le fichier manifeste de pré-cache.

Quand ne pas utiliser injectManifest

N'utilisez pas injectManifest dans les cas suivants:

  • Vous ne souhaitez pas utiliser la pré-mise en cache dans votre service worker.
  • nos exigences concernant les 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 une manière d'utiliser Workbox indépendamment du framework dans votre processus de compilation, trois options s'offrent à vous:

  1. workbox-cli
  2. workbox-build l'outil de ligne de commande.
  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 si vous ne souhaitez pas lier votre service worker fourni par Workbox à un framework particulier. Examinons rapidement chacune de ces options pour savoir laquelle vous conviendrait le mieux.

workbox-cli

Si vous recherchez le niveau d'accès le plus bas possible avec 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 va vous poser quelques questions, dont les réponses serviront à configurer un projet à l'aide d'un fichier workbox-config.js que vous pourrez personnaliser selon vos besoins. Voici un exemple:

// 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 automatiquement les méthodes generateSW ou injectManifest. Le texte d'aide de la CLI contient plus d'informations et d'exemples d'utilisation.

workbox-build

workbox-cli est un wrapper autour du module workbox-build. Vous pouvez également 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 utiliserez les méthodes generateSW ou injectManifest directement dans un script Node, 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 écrit le service worker généré dans le répertoire dist lors de l'exécution de la commande node build-sw.mjs.

Utiliser un bundler

Différents bundles possèdent leurs propres plug-ins Workbox, mais le seul bundler 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 en majuscules les noms de ces méthodes 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 les mêmes que generateSW ou injectManifest, mais elles se chevauchent fortement. En particulier, vous n'avez pas besoin de spécifier une option globDirectory pour GenerateSW (ni vous en pouvez), car Webpack sait déjà où vos éléments de production sont regroupés.

Utiliser un framework

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 avec Workbox par défaut. Les différentes intégrations de framework avec Workbox sont présentées plus loin dans un article ultérieur.

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

Que faire si je ne dispose pas d'un processus de compilation ?

Ce document suppose que votre projet dispose d'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 depuis un CDN ou localement, et créer 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 en matière de framework ou de chaîne d'outils. Toutes ces possibilités vous permettront d'effectuer la mise en cache préalable et la mise en cache de l'environnement d'exécution à l'aide de deux méthodes, tout en offrant une plus grande flexibilité pour créer des service workers avec des fonctionnalités plus avancées si nécessaire.