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:
workbox-cli
workbox-build
.- 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.