création de boîte de travail

Le module workbox-build s'intègre à un processus de compilation basé sur des nœuds et peut générer un service worker complet ou simplement une liste d'éléments à précharger qui pourraient être utilisés dans un service worker existant.

Les deux modes que la plupart des développeurs utiliseront sont generateSW et injectManifest. Les réponses aux questions suivantes peuvent vous aider à choisir le mode et la configuration à utiliser.

Quel mode utiliser ?

generateSW

Le mode generateSW crée un fichier de service worker pour vous, personnalisé à l'aide d'options de configuration, et l'écrit sur le disque.

Dans quel contexte utiliser generateSW ?

  • Vous souhaitez prémettre des fichiers en cache.
  • Vous avez des besoins simples en matière de mise en cache du temps d'exécution.

Quand NE PAS utiliser generateSW

  • Vous souhaitez utiliser d'autres fonctionnalités Service Worker (par exemple, Web Push).
  • Vous souhaitez importer des scripts supplémentaires ou ajouter une logique pour les stratégies de mise en cache personnalisées.

injectManifest

Le mode injectManifest génère une liste d'URL à précharger et ajoute ce manifeste de préchargement à 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 prémettre en cache des fichiers.
  • Vous devez personnaliser le routage et les stratégies.
  • Vous souhaitez utiliser votre service worker avec d'autres fonctionnalités de la plate-forme (par exemple, Web Push).

Quand NE PAS utiliser injectManifest

  • Vous souhaitez ajouter un service worker à votre site de la manière la plus simple possible.

Mode generateSW

Vous pouvez utiliser le mode generateSW dans un script de compilation basé sur des nœuds, en utilisant les options de configuration les plus courantes, comme suit :

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

Cela générera un service worker avec une configuration de préchargement pour tous les fichiers sélectionnés par votre configuration et les règles de mise en cache du runtime fournies.

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

Mode injectManifest

Vous pouvez utiliser le mode injectManifest dans un script de compilation basé sur des nœuds, en utilisant les options de configuration les plus courantes, comme suit :

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

Cela créera un manifeste de précache basé sur les fichiers récupérés par votre configuration et l'injectera dans votre fichier de service worker existant.

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

Autres modes

Nous pensons que generateSW ou injectManifest répondront aux besoins de la plupart des développeurs. Toutefois, un autre mode est compatible avec workbox-build et peut être adapté à certains cas d'utilisation.

Mode getManifest

Ce mode est conceptuellement semblable au mode injectManifest, mais au lieu d'ajouter le fichier manifeste au fichier source du service worker, il renvoie le tableau des entrées du fichier manifeste, ainsi que des informations sur le nombre d'entrées et la taille totale.

Vous pouvez utiliser le mode injectManifest dans un script de compilation basé sur des nœuds, en utilisant les options de configuration les plus courantes, comme suit :

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

Types

BasePartial

Propriétés

  • additionalManifestEntries

    (string | ManifestEntry)[] facultatif

    Liste des entrées à prémettre en cache, en plus de celles générées dans la configuration de compilation.

  • dontCacheBustURLsMatching

    Expression régulière facultative

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

  • manifestTransforms

    ManifestTransform[] facultatif

    Une ou plusieurs fonctions qui seront appliquées séquentiellement 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

    La valeur par défaut est 2097152.

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

  • modifyURLPrefix

    object facultatif

    Objet mappant les préfixes de chaîne aux valeurs de chaîne de remplacement. Cela peut être utilisé, 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, qui offre plus de flexibilité. Vous pouvez ainsi fournir une fonction qui modifie les entrées du fichier manifeste en utilisant la logique de votre choix.

    Exemple d'utilisation :

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

BuildResult

Type

Omit<GetManifestResult"manifestEntries"
> & object

Propriétés

  • filePaths

    chaîne[]

GeneratePartial

Propriétés

  • 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

    chaîne facultatif

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

  • 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 plus anciennes et 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

    chaîne facultatif

    Si une requête de navigation pour une URL se terminant par / ne correspond pas à une URL pré-mise en cache, cette valeur sera ajoutée à l'URL et une correspondance de pré-mise en cache sera recherchée. Cette valeur doit correspondre à celle utilisée par votre serveur Web pour l'index de répertoire.

  • disableDevLogs

    booléen facultatif

    La valeur par défaut est false.

  • ignoreURLParametersMatching

    RegExp[] facultatif

    Tous les noms de paramètres de recherche qui correspondent à l'une des expressions régulières de ce tableau seront supprimés avant la recherche d'une correspondance de précache. Cela peut être utile si vos utilisateurs sont susceptibles de 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 s'avère utile lorsque vous souhaitez laisser Workbox créer votre fichier de service worker de premier niveau, mais que vous voulez inclure du code supplémentaire, tel qu'un écouteur d'événements push.

  • 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 premier niveau ou divisé en un fichier distinct qui doit être déployé avec le service worker. En gardant le runtime séparé, les utilisateurs n'auront pas à retélécharger le code Workbox chaque fois que votre service worker de premier niveau change.

  • mode

    chaîne facultatif

    La valeur par défaut est "production".

    Si la valeur est définie sur "production", un bundle de service worker optimisé qui exclut les informations de débogage sera produit. Si elle n'est pas configurée explicitement ici, la valeur process.env.NODE_ENV sera utilisée. Si elle ne l'est pas non plus, la valeur 'production' sera utilisée.

  • navigateFallback

    chaîne 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 pré-mises en cache seront traitées avec le code HTML de l'URL fournie. Vous devez transmettre l'URL d'un document HTML figurant dans votre fichier manifeste de précache. Il est destiné à être utilisé dans un scénario d'application monopage, dans lequel vous souhaitez que toutes les navigations utilisent un HTML App Shell commun.

  • navigateFallbackAllowlist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières qui limite les URL auxquelles le comportement navigateFallback configuré s'applique. 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 refus 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, car vos utilisateurs pourraient rencontrer des ralentissements lorsqu'ils naviguent sur votre site.

  • navigateFallbackDenylist

    RegExp[] facultatif

    Tableau facultatif d'expressions régulières qui limite les URL auxquelles le comportement navigateFallback configuré s'applique. 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 refus 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, car vos utilisateurs pourraient rencontrer des ralentissements lorsqu'ils naviguent sur votre site.

  • navigationPreload

    booléen facultatif

    La valeur par défaut est false.

    Indique s'il faut activer la préchargement de la navigation dans le service worker généré. Si la valeur est définie sur "true", vous devez également utiliser runtimeCaching pour configurer une stratégie de réponse appropriée qui correspondra aux demandes de navigation et utilisera la réponse préchargée.

  • offlineGoogleAnalytics

    boolean | GoogleAnalyticsInitializeOptions facultatif

    La valeur par défaut est false.

    Contrôle si la prise en charge de Google Analytics hors connexion doit être incluse ou non. Lorsque true, l'appel à initialize() de workbox-google-analytics sera ajouté à votre 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. Elles 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 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.

    Indique s'il faut ajouter un appel inconditionnel à skipWaiting() 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.

  • sourcemap

    booléen facultatif

    La valeur par défaut est true.

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

GenerateSWOptions

Type

BasePartial, GlobPartial, GeneratePartial, RequiredSWDestPartial et OptionalGlobDirectoryPartial

GetManifestOptions

Type

BasePartial, GlobPartial et RequiredGlobDirectoryPartial

GetManifestResult

Propriétés

  • nombre

    Total

  • manifestEntries

    ManifestEntry[]

  • taille

    Total

  •  avertissements

    chaîne[]

GlobPartial

Propriétés

  • globFollow

    booléen facultatif

    La valeur par défaut est true.

    Détermine si les liens symboliques sont suivis lors de la génération du fichier manifeste de précache. Pour en savoir plus, consultez la définition de follow dans la documentation glob.

  • globIgnores

    string[] facultatif

    La valeur par défaut est : ["**\/node_modules\/**\/*"]

    Ensemble de modèles correspondant aux fichiers à exclure systématiquement lors de la génération du fichier manifeste de précache. Pour en savoir plus, consultez la définition de ignore dans la documentation glob.

  • globPatterns

    string[] facultatif

    La valeur par défaut est ["**\/*.{js,wasm,css,html}"].

    Les fichiers correspondant à l'un de ces modèles seront inclus dans le fichier manifeste de précache. Pour en savoir plus, consultez l'introduction à glob.

  • templatedURLs

    object facultatif

    Si une URL est affichée en fonction d'une logique côté serveur, son contenu peut dépendre de plusieurs fichiers ou d'une autre valeur de chaîne unique. Les clés de cet objet sont des URL rendues côté serveur. Si les valeurs sont un tableau de chaînes, elles seront interprétées comme des modèles glob, et le contenu de tous les fichiers correspondant aux modèles sera utilisé pour versionner l'URL de manière unique. Si elle est utilisée avec une seule chaîne, elle sera interprétée comme des informations de version uniques que vous avez générées pour une URL donnée.

InjectManifestOptions

Type

BasePartial, GlobPartial, InjectPartial, RequiredSWDestPartial et RequiredGlobDirectoryPartial

InjectPartial

Propriétés

  • injectionPoint

    chaîne facultatif

    La valeur par défaut est "self.__WB_MANIFEST".

    Chaîne à trouver dans le fichier swSrc. Une fois trouvé, il sera remplacé par le manifeste de précache généré.

  • swSrc

    chaîne

    Chemin d'accès et nom de fichier du fichier Service Worker qui sera lu lors du processus de compilation, par rapport au répertoire de travail actuel.

ManifestEntry

Propriétés

  • intégrité

    chaîne facultatif

  • la révision

    chaîne

  • url

    chaîne

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

Type

fonction

Paramètres

  • manifestEntries

    (ManifestEntry & object)[]

    • taille

      Total

  • compilation

    unknown (inconnu) facultatif

Renvoie

ManifestTransformResult

Propriétés

  • fichier manifeste

    (ManifestEntry & object)[]

    • taille

      Total

  •  avertissements

    string[] facultatif

OptionalGlobDirectoryPartial

Propriétés

  • globDirectory

    chaîne facultatif

    Répertoire local que vous souhaitez faire correspondre à globPatterns. Le chemin d'accès est relatif au répertoire actuel.

RequiredGlobDirectoryPartial

Propriétés

  • globDirectory

    chaîne

    Répertoire local que vous souhaitez faire correspondre à globPatterns. Le chemin d'accès est relatif au répertoire actuel.

RequiredSWDestPartial

Propriétés

  • swDest

    chaîne

    Chemin d'accès et nom de fichier du fichier Service Worker qui sera créé par le processus de compilation, par rapport au répertoire de travail actuel. Il doit se terminer par ".js".

RuntimeCaching

Propriétés

StrategyName

Énumération

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

Type

BasePartial, WebpackPartial, GeneratePartial et WebpackGenerateSWPartial

WebpackGenerateSWPartial

Propriétés

  • 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().

  • swDest

    chaîne facultatif

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

    Nom de l'élément du fichier Service Worker créé par ce plug-in.

WebpackInjectManifestOptions

Type

BasePartial, WebpackPartial, InjectPartial et WebpackInjectManifestPartial

WebpackInjectManifestPartial

Propriétés

  • compileSrc

    booléen facultatif

    La valeur par défaut est true.

    Lorsque la valeur est true (par défaut), le fichier swSrc est compilé par webpack. Lorsque false, la compilation n'aura pas lieu (et webpackCompilationPlugins ne peut pas être utilisé). Définissez la valeur sur false si vous souhaitez injecter le fichier manifeste dans, par exemple, un fichier JSON.

  • swDest

    chaîne facultatif

    Nom de l'élément du fichier Service Worker qui sera créé par ce plug-in. Si ce paramètre est omis, le nom sera basé sur le nom swSrc.

  • webpackCompilationPlugins

    any[] facultatif

    Plug-ins webpack facultatifs qui seront utilisés lors de la compilation du fichier d'entrée swSrc. Valide uniquement si compileSrc est défini sur true.

WebpackPartial

Propriétés

  • chunks

    string[] facultatif

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

  • exclure

    (string | RegExp | function)[] facultatif

    Un ou plusieurs spécificateurs utilisés pour exclure des éléments du fichier manifeste de précache. Cette option 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écache.

  • inclure

    (string | RegExp | function)[] facultatif

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

  • mode

    chaîne facultatif

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

Méthodes

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
): Promise<string>

Cela copie un ensemble de bibliothèques d'exécution utilisées par Workbox dans un répertoire local, qui doit être déployé avec votre fichier de service worker.

Au lieu de déployer ces copies locales, vous pouvez utiliser Workbox à partir de son URL CDN officielle.

Cette méthode est exposée au profit des développeurs utilisant workbox-build.injectManifest qui préféreraient ne pas utiliser les copies CDN de Workbox. Les développeurs qui utilisent workbox-build.generateSW n'ont pas besoin d'appeler explicitement cette méthode.

Paramètres

  • destDirectory

    chaîne

    Chemin d'accès au répertoire parent sous lequel le nouveau répertoire de bibliothèques sera créé.

Renvoie

  • Promise<string>

    Nom du répertoire créé.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

Cette méthode crée une liste d'URL à précharger, appelée "manifeste de préchargement", en fonction des options que vous fournissez.

Il accepte également des options supplémentaires qui configurent le comportement du service worker, comme les règles runtimeCaching qu'il doit utiliser.

En fonction du fichier manifeste de précache et de la configuration supplémentaire, il écrit un fichier de service worker prêt à l'emploi sur le disque à l'emplacement swDest.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

Paramètres

Renvoie

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
): Promise<GetManifestResult>

Cette méthode renvoie une liste d'URL à précharger, appelée "manifeste de préchargement", ainsi que des informations sur le nombre d'entrées et leur taille, en fonction des options que vous fournissez.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

Paramètres

Renvoie

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
): string

Paramètres

  • moduleName

    chaîne

  • buildType

    BuildType

Renvoie

  • chaîne

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

Cette méthode crée une liste d'URL à précharger, appelée "manifeste de préchargement", en fonction des options que vous fournissez.

Le fichier manifeste est injecté dans le fichier swSrc, et la chaîne d'espace réservé injectionPoint détermine l'emplacement du fichier manifeste dans le fichier.

Le fichier service worker final, avec le fichier manifeste injecté, est écrit sur le disque à l'emplacement swDest.

Cette méthode ne compilera ni n'inclura votre fichier swSrc. Elle gère uniquement l'injection du fichier manifeste.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

Paramètres

Renvoie