plug-in webpack boîte de travail

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

Les plug-ins sont implémentés sous la forme de 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 à utiliser.

Le plug-in à utiliser

GenerateSW

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

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

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 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.

Plug-in GenerateSW

Vous pouvez ajouter le plug-in GenerateSW à la configuration de votre pack Web 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érera un service worker avec une configuration de mise en cache préalable pour tous les éléments Webpack récupérés par votre configuration, ainsi que les règles de mise en cache de l'environnement d'exécution fournies.

Vous trouverez un ensemble complet d'options de configuration dans la documentation de référence.

Plug-in InjectManifest

Vous pouvez ajouter le plug-in InjectManifest à la configuration de votre pack Web 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: '...',
    }),
  ],
};

Cette opération crée un fichier manifeste de pré-cache basé sur les éléments webpack récupérés par votre configuration et l'injecte dans votre fichier service worker groupé et compilé.

Vous trouverez un ensemble complet d'options de configuration dans la documentation de référence.

Informations supplémentaires

Pour en savoir plus sur l'utilisation des plug-ins dans le contexte d'un build Webpack plus important, consultez la section Progressive Web Application (Application Web progressive) 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

    (string | ManifestEntry)[] facultatif

    Une liste des entrées à mettre en pré-cache, en plus des entrées générées dans le cadre de la configuration de compilation.

  • babelPresetEnvTargets

    string[] facultatif

    La valeur par défaut est: ["chrome >= 56"]

    Les cibles à transmettre à babel-preset-env lors de la transpilation du bundle de service worker.

  • cacheId

    string 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 fragment dont les fichiers de sortie correspondants doivent être inclus dans le fichier manifeste de précache.

  • 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 d'anciennes versions incompatibles.

  • clientsClaim

    Booléen facultatif

    La valeur par défaut est false.

    Indique si le service worker doit commencer à contrôler les clients existants dès son activation.

  • directoryIndex

    string facultatif

    Si une requête de navigation pour une URL se terminant par / ne correspond pas à une URL en pré-cache, cette valeur sera ajoutée à l'URL, et la correspondance sera vérifiée. Ce champ doit être défini sur l'index de répertoire utilisé par votre serveur Web.

  • disableDevLogs

    Booléen facultatif

    La valeur par défaut est false.

  • dontCacheBustURLsMatching

    Expression régulière (facultatif)

    Les éléments correspondant à cette règle seront considérés comme disposant d'une version unique via leur URL et exemptés du cache busting HTTP standard lors du remplissage de la mise en cache préalable. Bien que cela ne soit pas obligatoire, si votre processus de compilation existant insère déjà une valeur [hash] dans chaque nom de fichier, vous devez fournir une expression régulière qui la détectera, car elle réduira la bande passante consommée lors de la mise en cache préalable.

  • exclure

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

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

  • excludeChunks

    string[] facultatif

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

  • ignoreURLParametersMatching

    RegExp[] facultatif

    Tous les noms de paramètres de recherche correspondant à l'une des expressions régulières de ce tableau seront supprimés avant la recherche d'une correspondance en pré-cache. Cette fonctionnalité est utile si vos utilisateurs demandent des URL contenant, par exemple, des paramètres d'URL utilisés pour suivre la source du trafic. Si aucune valeur n'est fournie, la valeur par défaut est [/^utm_/, /^fbclid$/].

  • importScripts

    string[] facultatif

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

  • importScriptsViaChunks

    string[] facultatif

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

  • inclut

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

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

  • inlineWorkboxRuntime

    Booléen facultatif

    La valeur par défaut est 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 un fichier distinct qui doit être déployé en même temps que le service worker. Si vous conservez l'environnement d'exécution séparément, les utilisateurs n'auront pas à télécharger à nouveau le code de la boîte de travail chaque fois que votre service worker de niveau supérieur change.

  • 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, les transformations correspondantes sont appliquées en premier.

  • maximumFileSizeToCacheInBytes

    numéro facultatif

    La valeur par défaut est 2097152.

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

  • Standard

    string facultatif

    S'il est défini sur "production", un bundle de service worker optimisé qui exclut les informations de débogage sera créé. 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

    Une chaîne de mappage d'objets est précédée de valeurs de chaîne de remplacement. Cela permet, par exemple, de supprimer ou d'ajouter un préfixe de chemin d'accès à partir d'une entrée du fichier manifeste si votre configuration d'hébergement Web ne correspond pas à la configuration de votre système de fichiers local. Comme alternative plus flexible, vous pouvez utiliser l'option manifestTransforms et fournir une fonction qui modifie les entrées du fichier manifeste à l'aide de la logique que vous fournissez.

    Exemples d'utilisation :

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

    string facultatif

    La valeur par défaut est: null

    Si cette option est spécifiée, toutes les requêtes de navigation pour les URL qui ne sont pas en pré-cache sont traitées avec le code HTML de l'URL fournie. Vous devez transmettre l'URL d'un document HTML répertorié dans votre fichier manifeste de pré-cache. Elle est destinée à être utilisée dans un scénario d'application monopage, dans lequel vous souhaitez que toutes les navigations utilisent le code HTML App Shell courant.

  • navigateFallbackAllowlist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières limitant les URL auxquelles s'applique le comportement navigateFallback configuré. Cela 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 est prioritaire.

    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, sinon vos utilisateurs risquent de constater du retard lorsqu'ils naviguent sur votre site.

  • navigateFallbackDenylist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières limitant les URL auxquelles s'applique le comportement navigateFallback configuré. Cela est utile si seul un sous-ensemble des URL de votre site doit être traité comme faisant partie d'une application à page unique. Si navigateFallbackDenylist et navigateFallbackAllowlist sont tous les deux configurés, la liste de blocage est prioritaire.

    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, sinon vos utilisateurs risquent de constater du retard lorsqu'ils naviguent 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 ce paramètre est défini sur "true", vous devez également utiliser runtimeCaching pour configurer une stratégie de réponse appropriée correspondant aux requêtes de navigation et utiliser la réponse préchargée.

  • offlineGoogleAnalytics

    booléen | GoogleAnalyticsInitializeOptions facultatif

    La valeur par défaut est false.

    Détermine si la compatibilité avec Google Analytics hors connexion doit être ou non. Lorsque la valeur est true, l'appel du 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 de l'environnement 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 avez définie.

    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

    La valeur par défaut est false.

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

  • carte source

    Booléen facultatif

    La valeur par défaut est true.

    Indique s'il faut créer un mappage source pour les fichiers de service worker générés.

  • swDest

    string facultatif

    La valeur par défaut est "service-worker.js"

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

InjectManifest

Cette classe permet de compiler un fichier de service worker fourni via swSrc, et d'injecter dans ce service worker 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 Webpack principale.

// 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

  • constructor

    void

    Crée une instance d'InjectManifest.

    La fonction constructor se présente comme suit : 

    (config: WebpackInjectManifestOptions) => {...}

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

Propriétés

default

Type

objet

Propriétés

  • GenerateSW

    requête

  • InjectManifest

    requête