création de boîte de travail

Le module workbox-build s'intègre à un processus de compilation basé sur Node et peut générer un service worker complet ou simplement une liste d'éléments à pré-cacher 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 appropriés.

Mode à utiliser

generateSW

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

Dans quel contexte utiliser generateSW ?

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

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 mode injectManifest génère une liste d'URL à précharger et ajoute ce fichier manifeste de préchargement à 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 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 Node, 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.`);
});

Un service worker avec configuration de préchargement est généré pour tous les fichiers 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.

Mode injectManifest

Vous pouvez utiliser le mode injectManifest dans un script de compilation basé sur Node, 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.`);
});

Un fichier manifeste de préchargement est alors créé en fonction des fichiers détectés par votre configuration et injecté dans votre fichier de service worker existant.

Vous trouverez la liste complète des 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, workbox-build propose un autre mode qui 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 dans le 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 Node, 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 la liste complète des options de configuration dans la documentation de référence.

Types

BasePartial

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.

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

  • 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 permet de déterminer la taille maximale des fichiers qui seront préchargés. Vous évitez ainsi de pré-cacher par inadvertance de très volumineux fichiers qui auraient pu correspondre accidentellement à l'un de vos modèles.

  • modifyURLPrefix

    objet facultatif

    Objet mappant les préfixes de chaîne aux 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. Pour plus de flexibilité, 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.

    Exemple d'utilisation :

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

BuildResult

Type

Omettre<GetManifestResult"manifestEntries"
> & objet

Propriétés

  • filePaths

    chaîne[]

GeneratePartial

Propriétés

  • babelPresetEnvTargets

    string[] facultatif

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

    Cibles à transmettre à babel-preset-env lors de la transcompilation du bundle du service worker.

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

  • cleanupOutdatedCaches

    booléen facultatif

    Valeur par défaut: 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 sera vérifiée pour une correspondance de précharge. 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

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

  • 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 gardant 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 changera.

  • mode

    chaîne facultatif

    Valeur par défaut: "production"

    Si cette valeur est définie sur "production", un bundle de service worker optimisé qui exclut les informations de débogage est généré. Si elle n'est pas explicitement configurée ici, la valeur process.env.NODE_ENV est utilisée, et à défaut, la valeur 'production' est utilisée.

  • navigateFallback

    chaîne facultatif

    Valeur par défaut: 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, car vos utilisateurs pourraient rencontrer des retards lors de 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

    Valeur par défaut: false

    Indique si le préchargement de navigation doit être activé ou non 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

    Indique si la compatibilité avec Google Analytics hors connexion doit être incluse ou non. Lorsque true, l'appel de initialize() de workbox-google-analytics est 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. Ils sont ensuite traduits en appels workbox-routing.registerRoute à l'aide de la configuration de la correspondance et du 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 client de déclencher skipWaiting() en appelant postMessage({type: 'SKIP_WAITING'}) sur un service worker en attente.

  • sourcemap

    booléen facultatif

    Valeur par défaut: true

    Indique si un fichier sourcemap doit être créé pour les fichiers de service worker générés.

GenerateSWOptions

GetManifestOptions

GetManifestResult

Propriétés

  • nombre

    Nombre

  • manifestEntries
  • taille

    Nombre

  •  avertissements

    chaîne[]

GlobPartial

Propriétés

  • globFollow

    booléen facultatif

    Valeur par défaut: true

    Détermine si les liens symboliques sont suivis lors de la génération du fichier manifeste de préchargement. Pour en savoir plus, consultez la définition de follow dans la documentation de 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échargement. Pour en savoir plus, consultez la définition de ignore dans la documentation de glob.

  • globPatterns

    string[] facultatif

    Valeur par défaut: ["**\/*.{js,wasm,css,html}"]

    Les fichiers correspondant à l'un de ces formats seront inclus dans le fichier manifeste de préchargement. Pour en savoir plus, consultez la présentation de glob.

  • globStrict

    booléen facultatif

    Valeur par défaut: true

    Si la valeur est "true", une erreur de lecture d'un répertoire lors de la génération d'un fichier manifeste de préchargement entraîne l'échec de la compilation. Si la valeur est "false", le répertoire problématique sera ignoré. Pour en savoir plus, consultez la définition de strict dans la documentation sur glob.

  • templatedURLs

    objet 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 générées par le serveur. Si les valeurs sont un tableau de chaînes, elles seront interprétées comme des formats glob, et le contenu de tous les fichiers correspondant aux formats sera utilisé pour créer une version unique de l'URL. S'il est utilisé avec une seule chaîne, il sera interprété comme des informations de gestion des versions uniques que vous avez générées pour une URL donnée.

InjectManifestOptions

InjectPartial

Propriétés

  • injectionPoint

    chaîne facultatif

    Valeur par défaut: "self.__WB_MANIFEST"

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

  • swSrc

    chaîne

    Chemin d'accès et nom de fichier du fichier du 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

  • Révision

    chaîne

  • url

    chaîne

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
)

Type

fonction

Paramètres

  • manifestEntries

    (ManifestEntry & object)[]

    • taille

      Nombre

  • compilation

    unknown facultatif

ManifestTransformResult

Propriétés

  • fichier manifeste

    (ManifestEntry & object)[]

    • taille

      Nombre

  •  avertissements

    string[] facultatif

OptionalGlobDirectoryPartial

Propriétés

  • globDirectory

    chaîne facultatif

    Répertoire local avec lequel 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 avec lequel 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 de 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

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

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

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

WebpackInjectManifestOptions

WebpackInjectManifestPartial

Propriétés

  • compileSrc

    booléen facultatif

    Valeur par défaut: true

    Lorsque la valeur est true (valeur par défaut), le fichier swSrc est compilé par webpack. Lorsque false, la compilation n'a 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'asset du fichier de service worker qui sera créé par ce plug-in. Si vous ne le spécifiez pas, le nom sera basé sur le nom swSrc.

  • webpackCompilationPlugins

    any[] facultatif

    Plugins 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

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

  • exclure

    (chaîne | RegExp | fonction)[] 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.

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

  • mode

    chaîne facultatif

    Si cette valeur est définie 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.

Méthodes

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: 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 pour le bénéfice des développeurs qui utilisent workbox-build.injectManifest et qui préfèrent 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 nouvellement créé.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

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

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

Sur la base du fichier manifeste de préchargement 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,
)

Cette méthode renvoie une liste d'URL à précacher, appelée "fichier 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,
)

Paramètres

  • moduleName

    chaîne

  • buildType

    BuildType

Renvoie

  • chaîne

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

Cette méthode crée une liste d'URL à précharger, appelée "fichier manifeste de précharge", 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 de service worker final, avec le fichier manifeste injecté, est écrit sur le disque à swDest.

Cette méthode ne compile ni ne regroupe pas votre fichier swSrc. Elle gère simplement 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