plug-in webpack boîte de travail

Workbox fournit deux plug-ins webpack: l'un qui génère un service worker complet pour vous et l'autre qui génère une liste d'éléments à précacher qui est injectée dans un fichier de service worker.

Les plug-ins sont implémentés en tant que deux classes dans le module workbox-webpack-plugin, nommées GenerateSW et InjectManifest. Les réponses aux questions suivantes peuvent vous aider à choisir le plug-in et la configuration appropriés.

Quel plug-in utiliser ?

GenerateSW

Le plug-in GenerateSW crée un fichier de service worker pour vous et l'ajoute au pipeline d'éléments webpack.

Dans quel contexte utiliser GenerateSW ?

  • Vous souhaitez effectuer une pré-cache des fichiers.
  • Vous avez des besoins simples de mise en cache des environnements d'exécution.

Quand 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 supplémentaire pour des stratégies de mise en cache personnalisées.

InjectManifest

Le plug-in InjectManifest génère une liste d'URL à mettre en pré-cache et ajoute ce fichier manifeste de pré-cache à un fichier de service worker existant. Sinon, le fichier restera tel quel.

Dans quel contexte utiliser InjectManifest ?

  • Vous souhaitez avoir plus de contrôle sur votre service worker.
  • Vous souhaitez pré-cacher des fichiers.
  • Vous devez personnaliser le routage et les stratégies.
  • Vous voulez utiliser votre service worker avec d'autres fonctionnalités de la plate-forme (par exemple, le Web push).

Quand NE PAS utiliser InjectManifest

  • Vous recherchez la méthode la plus simple pour ajouter un service worker à votre site.

Plug-in GenerateSW

Vous pouvez ajouter le plug-in GenerateSW à votre configuration webpack comme suit:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

Cela génère un service worker avec une configuration de préchargement pour tous les éléments webpack détectés par votre configuration et les règles de mise en cache d'exécution fournies.

Vous trouverez la liste complète des options de configuration dans la documentation de référence.

Plug-in InjectManifest

Vous pouvez ajouter le plug-in InjectManifest à votre configuration webpack comme suit:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

Cela crée un fichier manifeste de préchargement basé sur les éléments webpack détectés par votre configuration et l'injecte dans votre fichier de service worker groupé et compilé.

Toutes les options de configuration sont disponibles dans la documentation de référence.

Informations supplémentaires

Pour obtenir des conseils sur l'utilisation des plug-ins dans le contexte d'un build webpack plus important, consultez la section Progressive Web Application de la documentation webpack.

Types

GenerateSW

Cette classe permet de créer un fichier de service worker prêt à l'emploi dans le cadre du processus de compilation webpack.

Utilisez une instance de GenerateSW dans le tableau plugins d'une configuration webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

Propriétés

GenerateSWConfig

Propriétés

  • additionalManifestEntries

    (chaîne | ManifestEntry)[] facultatif

    Liste des entrées à pré-cacher, en plus des entrées générées dans le cadre de la configuration de compilation.

  • babelPresetEnvTargets

    string[] facultatif

    Valeur par défaut: ["chrome >= 56"]

    Les cibles à transmettre à babel-preset-env lors du transpilage du bundle de nœuds de calcul du service.

  • cacheId

    chaîne facultatif

    ID facultatif à ajouter au début des noms de cache. Cela est principalement utile pour le développement local, où plusieurs sites peuvent être diffusés à partir de la même origine http://localhost:port.

  • blocs

    string[] facultatif

    Un ou plusieurs noms de blocs dont les fichiers de sortie correspondants doivent être inclus dans le fichier manifeste de préchargement.

  • cleanupOutdatedCaches

    booléen facultatif

    La valeur par défaut est false.

    Indique si Workbox doit tenter d'identifier et de supprimer les précaches créés par des versions antérieures incompatibles.

  • clientsClaim

    Booléen facultatif

    Valeur par défaut: false

    Indique si le service worker doit commencer à contrôler les clients existants dès qu'il s'active.

  • directoryIndex

    chaîne facultatif

    Si une requête de navigation pour une URL se terminant par / ne correspond pas à une URL préchargée, cette valeur sera ajoutée à l'URL et une correspondance de précharge sera effectuée. Ce paramètre doit être défini sur ce que votre serveur Web utilise pour son index de répertoire.

  • disableDevLogs

    booléen facultatif

    Valeur par défaut: false

  • dontCacheBustURLsMatching

    Expression régulière facultatif

    Les éléments qui correspondent à cette valeur seront considérés comme ayant une version unique via leur URL et seront exclus de la suppression de cache HTTP normale effectuée lors du remplissage du précache. Bien que cela ne soit pas obligatoire, il est recommandé que si votre processus de compilation existant insère déjà une valeur [hash] dans chaque nom de fichier, vous fournissiez une expression régulière qui le détecte, car cela réduira la bande passante consommée lors du préchargement.

  • exclure

    (chaîne | RegExp | function)[] facultatif

    Un ou plusieurs spécificateurs utilisés pour exclure des éléments du fichier manifeste de préchargement. Cette valeur est interprétée selon les mêmes règles que l'option exclude standard de webpack. Si aucune valeur n'est spécifiée, la valeur par défaut est [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] facultatif

    Un ou plusieurs noms de blocs dont les fichiers de sortie correspondants doivent être exclus du fichier manifeste de préchargement.

  • ignoreURLParametersMatching

    RegExp[] facultatif

    Tous les noms de paramètres de recherche qui correspondent à l'un des RegExp de ce tableau sont supprimés avant de rechercher une correspondance de préchargement. Cela est utile si vos utilisateurs peuvent demander des URL contenant, par exemple, des paramètres d'URL utilisés pour suivre la source du trafic. Si aucune valeur n'est spécifiée, la valeur par défaut est [/^utm_/, /^fbclid$/].

  • importScripts

    string[] facultatif

    Liste des fichiers JavaScript à transmettre à importScripts() dans le fichier service worker généré. Cela est utile lorsque vous souhaitez laisser Workbox créer votre fichier de service worker de premier niveau, mais que vous souhaitez inclure du code supplémentaire, tel qu'un écouteur d'événements push.

  • importScriptsViaChunks

    string[] facultatif

    Un ou plusieurs noms de blocs webpack. Le contenu de ces blocs sera inclus dans le service worker généré, via un appel à importScripts().

  • inclure

    (chaîne | RegExp | fonction)[] facultatif

    Un ou plusieurs spécificateurs utilisés pour inclure des éléments dans le fichier manifeste de préchargement. Cette valeur est interprétée selon les mêmes règles que l'option include standard de webpack.

  • inlineWorkboxRuntime

    booléen facultatif

    Valeur par défaut: false

    Indique si le code d'exécution de la bibliothèque Workbox doit être inclus dans le service worker de niveau supérieur ou divisé en fichier distinct à déployer avec le service worker. En conservant l'environnement d'exécution distinct, les utilisateurs n'auront pas à télécharger à nouveau le code Workbox chaque fois que votre service worker de niveau supérieur est modifié.

  • manifestEntries

    ManifestEntry[] facultatif

  • manifestTransforms

    ManifestTransform[] facultatif

    Une ou plusieurs fonctions qui seront appliquées de manière séquentielle au fichier manifeste généré. Si modifyURLPrefix ou dontCacheBustURLsMatching sont également spécifiés, leurs transformations correspondantes seront appliquées en premier.

  • maximumFileSizeToCacheInBytes

    number facultatif

    Valeur par défaut: 2097152

    Cette valeur peut être utilisée pour déterminer la taille maximale des fichiers à mettre en cache. Vous évitez ainsi de pré-cacher par inadvertance de très volumineux fichiers qui auraient pu correspondre accidentellement à l'un de vos modèles.

  • mode

    chaîne facultatif

    S'il est défini sur "production", un bundle de service worker optimisé qui exclut les informations de débogage est généré. Si elle n'est pas configurée explicitement ici, la valeur mode configurée dans la compilation webpack actuelle sera utilisée.

  • modifyURLPrefix

    objet facultatif

    Objet mappant des préfixes de chaîne à des valeurs de chaîne de remplacement. Vous pouvez l'utiliser, par exemple, pour supprimer ou ajouter un préfixe de chemin d'accès à une entrée de fichier manifeste si la configuration de votre hébergement Web ne correspond pas à celle de votre système de fichiers local. Vous pouvez également utiliser l'option manifestTransforms et fournir une fonction qui modifie les entrées du fichier manifeste à l'aide de la logique que vous fournissez.

    Exemple d'utilisation :

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    chaîne facultatif

    La valeur par défaut est: null

    Si vous le spécifiez, toutes les requêtes de navigation pour les URL qui ne sont pas préchargées seront traitées avec le code HTML de l'URL fournie. Vous devez transmettre l'URL d'un document HTML listé dans votre fichier manifeste de préchargement. Il est destiné à être utilisé dans un scénario d'application monopage, dans lequel vous souhaitez que toutes les navigations utilisent un code HTML de shell d'application commun.

  • navigateFallbackAllowlist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières qui limite les URL auxquelles le comportement navigateFallback configuré s'applique. Cette option est utile si seul un sous-ensemble des URL de votre site doit être traité comme faisant partie d'une application monopage. Si navigateFallbackDenylist et navigateFallbackAllowlist sont configurés, la liste de blocage prévaut.

    Remarque: Ces expressions régulières peuvent être évaluées par rapport à chaque URL de destination lors d'une navigation. Évitez d'utiliser des expressions régulières complexes. Dans le cas contraire, vos utilisateurs pourraient constater des retards dans la navigation sur votre site.

  • navigateFallbackDenylist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières qui limite les URL auxquelles le comportement navigateFallback configuré s'applique. Cette option est utile si seul un sous-ensemble des URL de votre site doit être traité comme faisant partie d'une application monopage. Si navigateFallbackDenylist et navigateFallbackAllowlist sont configurés, la liste de blocage prévaut.

    Remarque: Ces expressions régulières peuvent être évaluées par rapport à chaque URL de destination lors d'une navigation. Évitez d'utiliser des expressions régulières complexes, car vos utilisateurs pourraient rencontrer des retards lors de la navigation sur votre site.

  • navigationPreload

    booléen facultatif

    La valeur par défaut est false.

    Indique si le préchargement de navigation doit être activé dans le service worker généré. Lorsque cette valeur est définie sur "True", vous devez également utiliser runtimeCaching pour configurer une stratégie de réponse appropriée qui correspondra aux requêtes de navigation et utiliser la réponse préchargée.

  • offlineGoogleAnalytics

    booléen | GoogleAnalyticsInitializeOptions facultatif

    Valeur par défaut: false

    Détermine si la compatibilité avec Google Analytics hors connexion doit être prise en charge. Lorsque la valeur est true, l'appel au service initialize() de workbox-google-analytics est ajouté au service worker généré. Lorsqu'il est défini sur un Object, cet objet est transmis à l'appel initialize(), ce qui vous permet de personnaliser le comportement.

  • runtimeCaching

    RuntimeCaching[] facultatif

    Lorsque vous utilisez les outils de compilation de Workbox pour générer votre service worker, vous pouvez spécifier une ou plusieurs configurations de mise en cache d'exécution. Celles-ci sont ensuite traduites en appels workbox-routing.registerRoute à l'aide de la configuration de correspondance et de gestionnaire que vous définissez.

    Pour connaître toutes les options, consultez la documentation sur workbox-build.RuntimeCaching. L'exemple ci-dessous présente une configuration type, avec deux routes d'exécution définies:

  • skipWaiting

    Booléen facultatif

    Valeur par défaut: false

    Indique si un appel inconditionnel à skipWaiting() doit être ajouté au service worker généré. Si la valeur est false, un écouteur message est ajouté à la place, ce qui permet aux pages clientes de déclencher skipWaiting() en appelant postMessage({type: 'SKIP_WAITING'}) sur un service worker en attente.

  • fichier sourcemap

    booléen facultatif

    Valeur par défaut: true

    Permet de spécifier si un mappage source doit être créé pour les fichiers de service worker générés.

  • swDest

    chaîne facultatif

    Valeur par défaut: "service-worker.js"

    Nom de l'asset du fichier du service worker créé par ce plug-in.

InjectManifest

Cette classe permet de compiler un fichier de service worker fourni via swSrc et d'y injecter une liste d'URL et des informations de révision pour la mise en cache préalable en fonction du pipeline d'éléments webpack.

Utilisez une instance de InjectManifest dans le tableau plugins d'une configuration webpack.

En plus d'injecter le fichier manifeste, ce plug-in effectue une compilation du fichier swSrc à l'aide des options de la configuration principale de webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

Propriétés

Propriétés

default

Type

objet

Propriétés

  • GenerateSW

    requête

  • InjectManifest

    requête