L'interface de ligne de commande Workbox (incluse dans le package workbox-cli) consiste en un programme Node.js appelé "workbox" qui peut être exécuté à partir d'un environnement de ligne de commande Windows ou macOS, compatible avec UNIX. En arrière-plan, workbox-cli encapsule le module "workbox-build" et permet d'intégrer facilement Workbox dans un processus de compilation en ligne de commande, avec des configurations flexibles.
Installer la CLI
Pour installer la CLI avec Node, exécutez la commande suivante dans votre terminal:
npm install workbox-cli --global
Modes CLI
La CLI comporte quatre modes différents:
wizard: guide par étapes pour configurer Workbox pour votre projet.generateSW: génère un service worker complet pour vous.injectManifest: injecte les éléments à mettre en pré-cache dans votre projet.copyLibraries: copier les bibliothèques Workbox dans un répertoire.
wizard
L'assistant Workbox pose une série de questions sur la configuration de votre répertoire local et sur les fichiers que vous souhaitez mettre en pré-cache. Vos réponses permettent de générer un fichier de configuration qui peut ensuite être utilisé lors de l'exécution en mode generateSW.
La plupart des développeurs n'ont besoin d'exécuter l'assistant de boîte de travail qu'une seule fois. Vous êtes libre de personnaliser manuellement le fichier de configuration initial généré à l'aide de l'une des options de configuration de compilation compatibles.
Pour lancer l'assistant, exécutez la commande suivante:
npx workbox-cli wizard
generateSW
Vous pouvez utiliser la CLI Workbox pour générer un service worker complet à l'aide d'un fichier de configuration (comme le fichier généré par l'assistant).
Exécutez simplement la commande suivante:
npx workbox-cli generateSW path/to/config.js
Les développeurs qui sont satisfaits des fonctionnalités intégrées de prémise en cache et de mise en cache de l'environnement d'exécution de Workbox et qui n'ont pas besoin de personnaliser le comportement de leur service worker sont invités à utiliser le mode generateSW.
Dans quel contexte utiliser generateSW ?
- Vous souhaitez mettre les fichiers en pré-cache.
- Vous avez des besoins simples concernant la mise en cache de l'environnement d'exécution.
Dans quels cas NE PAS utiliser generateSW ?
- Vous souhaitez utiliser d'autres fonctionnalités de Service Worker (Web Push, par exemple).
- Vous souhaitez importer des scripts supplémentaires ou ajouter une logique pour des stratégies de mise en cache personnalisées.
injectManifest
Les développeurs qui souhaitent mieux contrôler le fichier final de service worker peuvent utiliser le mode injectManifest. Ce mode suppose que vous disposez d'un fichier de service worker (dont l'emplacement est spécifié dans config.js).
Lorsque workbox injectManifest est exécuté, il recherche une chaîne spécifique (precacheAndRoute(self.__WB_MANIFEST) par défaut) dans le fichier de service worker source. Il remplace le tableau vide par une liste d'URL à mettre en pré-cache et écrit le fichier de service worker à son emplacement de destination, en fonction des options de configuration de config.js.
Le reste du code de votre service worker source est conservé tel quel.
Vous pouvez utiliser Workbox dans ce mode comme suit:
npx workbox-cli injectManifest path/to/config.js
Dans quel contexte utiliser injectManifest ?
- Vous souhaitez mieux contrôler votre service worker.
- Vous souhaitez mettre les fichiers en pré-cache.
- Vous devez personnaliser le routage et les stratégies.
- Vous souhaitez utiliser votre service worker avec d'autres fonctionnalités de la plate-forme (Web Push, par exemple).
Dans quels cas NE PAS utiliser injectManifest ?
- Vous recherchez la méthode la plus simple pour ajouter un service worker à votre site.
copyLibraries
Ce mode est utile si vous souhaitez utiliser injectManifest et utiliser les fichiers de la bibliothèque Workbox hébergés sur votre propre origine au lieu d'utiliser le CDN.
Il vous suffit de l'exécuter avec un chemin d'accès pour écrire les fichiers:
npx workbox-cli copyLibraries third_party/workbox/
Intégration du processus de compilation
Pourquoi l'intégration de Workbox à mon processus de compilation est-elle nécessaire ?
Le projet Workbox contient un certain nombre de bibliothèques qui fonctionnent ensemble pour optimiser le service worker de votre application Web. Pour utiliser ces bibliothèques efficacement, Workbox doit être intégré au processus de compilation de votre application Web. Cela garantit que votre service worker est en mesure de mettre en cache efficacement tout le contenu critique de votre application Web et de maintenir ce contenu à jour.
workbox-cli est-il le bon choix pour mon processus de compilation ?
Si vous disposez d'un processus de compilation existant entièrement basé sur des scripts npm, workbox-cli est un bon choix.
Si vous utilisez actuellement webpack comme outil de compilation, il est préférable d'utiliser le workbox-webback-plugin.
Si vous utilisez actuellement Gulp, Grunt ou un autre outil de compilation basé sur Node.js, l'intégration de workbox-build à votre script de compilation est un meilleur choix.
Si vous n'avez aucun processus de compilation, vous devez en créer un avant d'utiliser Workbox pour mettre en cache l'un de vos éléments. Si vous vous rappelez d'exécuter Workbox-cli manuellement, vous risquez d'entraîner des erreurs. Si vous oubliez de l'exécuter, du contenu obsolète peut être diffusé auprès des visiteurs connus.
Installation et configuration
Après avoir installé workbox-cli comme dépendance de développement pour votre projet local, vous pouvez ajouter l'appel à workbox à la fin du script npm de votre processus de compilation existant:
Dans le fichier package.json:
{
"scripts": {
"build": "my-build-script && workbox <mode> <path/to/config.js>"
}
}
Remplacez <mode> par generateSW ou injectManifest (selon votre cas d'utilisation) et <path/to/config.js> par le chemin d'accès à vos options de configuration. Votre configuration a peut-être été créée automatiquement par workbox wizard ou modifiée manuellement.
Configuration
Options utilisées par generateSW
Vous trouverez un ensemble complet d'options de configuration dans la documentation de référence.
Options utilisées par injectManifest
Vous trouverez un ensemble complet d'options de configuration dans la documentation de référence.