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 générer une liste d'éléments à mettre en cache en pré-cache pouvant être utilisés dans un service worker existant.

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

Mode à utiliser

generateSW

Le mode generateSW crée automatiquement un fichier service worker personnalisé via les options de configuration et l'écrit sur le disque.

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

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 mise en cache préalable pour tous les fichiers 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.

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.`);
});

Cette opération crée un fichier manifeste en pré-cache basé sur les fichiers récupérés par votre configuration et l'injecte dans le fichier de service worker existant.

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

Modes supplémentaires

generateSW ou injectManifest devraient répondre aux besoins de la plupart des développeurs. Cependant, un autre mode compatible avec workbox-build peut convenir à certains cas d'utilisation.

Mode getManifest

Ce mode est semblable au mode injectManifest d'un point de vue conceptuel, mais au lieu d'ajouter le fichier manifeste dans le fichier service worker source, il renvoie le tableau des entrées du fichier manifeste, ainsi que des informations sur leur nombre et leur 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

    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.

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

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

  • 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',
    }
    

BuildResult

Type

Omit<GetManifestResult"manifestEntries"
>objet

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

    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.

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

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

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

  • Standard

    string facultatif

    La valeur par défaut est "production".

    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 process.env.NODE_ENV sera utilisée. À défaut, elle reviendra à 'production'.

  • 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

    boolean|GoogleAnalyticsInitializeOptions optional

    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.

GenerateSWOptions

GetManifestOptions

GetManifestResult

Propriétés

  • nombre

    number

  • manifestEntries
  • taille

    number

  •  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 ou non 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 sur glob.

  • globIgnores

    string[] facultatif

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

    Ensemble de modèles correspondant aux fichiers à toujours exclure 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 sur glob.

  • globPatterns

    string[] facultatif

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

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

  • globStrict

    Booléen facultatif

    La valeur par défaut est 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é-cache entraînera l'échec de la compilation. Si la valeur est "false", le répertoire problématique est 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 affiché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 à ces formats sera utilisé pour créer une version unique de l'URL. Lorsqu'elles sont utilisées avec une seule chaîne, elles seront interprétées 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

    string facultatif

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

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

  • swSrc

    chaîne

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

ManifestEntry

Propriétés

  • intégrité

    string facultatif

  • Révision

    chaîne

  • url

    chaîne

ManifestTransform()

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

Type

function

Paramètres

  • manifestEntries

    (ManifestEntry&object)[]

    • taille

      number

  • compilation

    inconnu facultatif

ManifestTransformResult

Propriétés

  • fichier manifeste

    (ManifestEntry&object)[]

    • taille

      number

  •  avertissements

    string[] facultatif

OptionalGlobDirectoryPartial

Propriétés

  • globDirectory

    string facultatif

    Répertoire local auquel 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 auquel 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 du fichier de service worker créé par le processus de compilation, par rapport au répertoire de travail actuel. Elle doit se terminer par ".js".

RuntimeCaching

Propriétés

StrategyName

Enum

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

WebpackGenerateSWOptions

WebpackGenerateSWPartial

Propriétés

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

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

WebpackInjectManifestOptions

WebpackInjectManifestPartial

Propriétés

  • compileSrc

    Booléen facultatif

    La valeur par défaut est true.

    Avec true (valeur par défaut), le fichier swSrc est compilé par webpack. Si la valeur est 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 un fichier JSON, par exemple.

  • swDest

    string facultatif

    Nom d'élément du fichier de service worker créé par ce plug-in. S'il est omis, le nom sera basé sur le nom swSrc.

  • webpackCompilationPlugins

    any[] facultatif

    Plug-ins webpack facultatifs à utiliser lors de la compilation du fichier d'entrée swSrc. N'est valide que si compileSrc est défini sur true.

WebpackPartial

Propriétés

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

  • exclure

    (string|RegExp|function)[] optional

    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.

  • inclure

    (string|RegExp|function)[] optional

    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.

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

Méthodes

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

Cette opération copie un ensemble de bibliothèques d'exécution utilisées par Workbox dans un répertoire local, qui doit être déployé avec le 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 dans lequel le nouveau répertoire de bibliothèques sera créé.

Renvoie

  • Promesse<chaîne>

    Nom du répertoire que vous venez de créer.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

Cette méthode crée une liste d'URL à mettre en cache (appelées "fichiers manifestes de pré-cache") en fonction des options que vous fournissez.

Il inclut également des options supplémentaires qui configurent le comportement du service worker, comme toutes 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,
)

Cette méthode renvoie une liste d'URL à mettre en pré-cache (appelée "fichier manifeste de pré-mise en cache"), 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 à mettre en cache (appelées "fichiers manifestes de pré-cache") 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.

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

Cette méthode ne compile pas et 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