workbox-webpack-plugin

Workbox bietet zwei Webpack-Plug-ins: eines, das einen vollständigen Service Worker für Sie generiert, und eines, das eine Liste von Assets generiert, um diese vorab im Cache zu speichern. Diese Plug-ins werden in eine Service Worker-Datei eingeschleust.

Die Plug-ins werden im Modul workbox-webpack-plugin als zwei Klassen mit den Namen GenerateSW und InjectManifest implementiert. Die Antworten auf die folgenden Fragen können Ihnen bei der Auswahl des richtigen Plug-ins und der richtigen Konfiguration helfen.

Welches Plug-in verwendet werden soll

GenerateSW

Das GenerateSW-Plug-in erstellt eine Service-Worker-Datei für Sie und fügt sie der Webpack-Asset-Pipeline hinzu.

Verwendung von GenerateSW

  • Sie möchten Dateien vorab im Cache speichern.
  • Sie haben einfache Anforderungen an das Laufzeit-Caching.

Wann sollte GenerateSW NICHT verwendet werden?

  • Sie möchten andere Service Worker-Funktionen verwenden (z.B. Web Push).
  • Sie möchten zusätzliche Skripts importieren oder zusätzliche Logik für benutzerdefinierte Caching-Strategien hinzufügen.

InjectManifest

Das InjectManifest-Plug-in generiert eine Liste von URLs, die vorab im Cache gespeichert werden sollen, und fügt dieses Precache-Manifest einer vorhandenen Service Worker-Datei hinzu. Ansonsten bleibt die Datei unverändert.

Verwendung von InjectManifest

  • Sie möchten mehr Kontrolle über Ihren Service Worker.
  • Sie möchten Dateien vorab im Cache speichern.
  • Du musst das Routing und die Strategien anpassen.
  • Sie möchten Ihren Service Worker mit anderen Plattformfunktionen verwenden, z.B. Web Push.

Wann sollte InjectManifest NICHT verwendet werden?

  • Sie möchten Ihrer Website am einfachsten einen Service Worker hinzufügen.

GenerateSW-Plug-in

So können Sie das GenerateSW-Plug-in in Ihre Webpack-Konfiguration einfügen:

// 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: ...,
    }),
  ],
};

Dadurch wird ein Service Worker mit Precaching-Einrichtung für alle Webpack-Assets, die von Ihrer Konfiguration aufgenommen wurden, und den bereitgestellten Laufzeit-Caching-Regeln generiert.

Eine vollständige Reihe an Konfigurationsoptionen finden Sie in der Referenzdokumentation.

InjectManifest-Plug-in

So können Sie das InjectManifest-Plug-in in Ihre Webpack-Konfiguration einfügen:

// 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: '...',
    }),
  ],
};

Dadurch wird ein Precache-Manifest erstellt, das auf den Webpack-Assets basiert, die von Ihrer Konfiguration aufgenommen wurden, und in Ihre gebündelte und kompilierte Service Worker-Datei eingefügt.

Eine vollständige Reihe an Konfigurationsoptionen finden Sie in der Referenzdokumentation.

Zusätzliche Informationen

Anleitungen zur Verwendung der Plug-ins im Kontext eines größeren Webpack-Builds finden Sie im Abschnitt Progressive Web Application der Webpack-Dokumentation.

Typen

GenerateSW

Diese Klasse unterstützt das Erstellen einer neuen, sofort einsatzbereiten Service Worker-Datei als Teil des Webpack-Kompilierungsprozesses.

Verwenden Sie eine Instanz von GenerateSW im plugins-Array einer Webpack-Konfiguration.

// 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: ...,
});

Attribute

GenerateSWConfig

Attribute

  • additionalManifestEntries

    (String | ManifestEntry)[] optional

    Eine Liste von Einträgen, die vorab im Cache gespeichert werden sollen, zusätzlich zu allen Einträgen, die im Rahmen der Build-Konfiguration generiert werden.

  • babelPresetEnvTargets

    string[] optional

    Standardwert: ["chrome >= 56"]

    Die Ziele, die beim Transpilieren des Service Worker-Bundles an babel-preset-env übergeben werden sollen.

  • cacheId

    String optional

    Eine optionale ID, die Cache-Namen vorangestellt wird. Dies ist vor allem für die lokale Entwicklung nützlich, bei der mehrere Websites vom selben http://localhost:port-Ursprung bereitgestellt werden können.

  • Chunks

    string[] optional

    Ein oder mehrere Chunk-Namen, deren entsprechende Ausgabedateien im Precache-Manifest enthalten sein sollen.

  • cleanupOutdatedCaches

    Boolescher Wert optional

    Standardwert ist: false

    Gibt an, ob Workbox versuchen soll, Precaches zu identifizieren und zu löschen, die von älteren, inkompatiblen Versionen erstellt wurden.

  • clientsClaim

    Boolescher Wert optional

    Standardwert ist: false

    Gibt an, ob der Service Worker mit der Steuerung vorhandener Clients beginnen soll, sobald er aktiviert wurde.

  • directoryIndex

    String optional

    Wenn eine Navigationsanfrage für eine URL mit der Endung / nicht mit einer vorab im Cache gespeicherten URL übereinstimmt, wird dieser Wert an die URL angehängt und auf eine Precache-Übereinstimmung geprüft. Dies sollte auf die Einstellung festgelegt werden, die Ihr Webserver für seinen Verzeichnisindex verwendet.

  • disableDevLogs

    Boolescher Wert optional

    Standardwert ist: false

  • dontCacheBustURLsMatching

    Regulärer Ausdruck optional

    Für Assets, die damit übereinstimmen, wird angenommen, dass sie über ihre URL eindeutig versioniert sind, und vom normalen HTTP-Cache-Busting ausgenommen, das beim Füllen des Vorcaches erfolgt. Es ist zwar nicht erforderlich, aber wenn Ihr vorhandener Build-Prozess bereits einen [hash]-Wert in jeden Dateinamen einfügt, sollten Sie einen RegExp bereitstellen, der dies erkennt, weil dadurch die beim Precaching belegte Bandbreite reduziert wird.

  • exclude

    (String | RegExp | Funktion)[] optional

    Ein oder mehrere Spezifizierer, mit denen Assets aus dem Precache-Manifest ausgeschlossen werden. Dies wird nach denselben Regeln wie die Standardoption exclude von webpack interpretiert. Wenn nicht angegeben, wird der Standardwert [/\.map$/, /^manifest.*\.js$] verwendet.

  • excludeChunks

    string[] optional

    Ein oder mehrere Chunk-Namen, deren entsprechende Ausgabedateien aus dem Precache-Manifest ausgeschlossen werden sollen.

  • ignoreURLParametersMatching

    Regulärer Ausdruck[] optional

    Alle Suchparameternamen, die mit einem RegExp in diesem Array übereinstimmen, werden entfernt, bevor nach einer Precache-Übereinstimmung gesucht wird. Das ist nützlich, wenn Ihre Nutzer möglicherweise URLs anfordern, die z. B. URL-Parameter enthalten, mit denen die Quelle des Traffics erfasst wird. Wenn Sie nichts angeben, wird der Standardwert [/^utm_/, /^fbclid$/] verwendet.

  • importScripts

    string[] optional

    Eine Liste der JavaScript-Dateien, die in der generierten Service-Worker-Datei an importScripts() übergeben werden sollen. Dies ist nützlich, wenn Sie möchten, dass Workbox Ihre Service Worker-Datei auf oberster Ebene erstellen soll, aber zusätzlichen Code enthalten soll, z. B. einen Push-Event-Listener.

  • importScriptsViaChunks

    string[] optional

    Ein oder mehrere Namen von Webpack-Chunks. Der Inhalt dieser Blöcke wird über einen Aufruf von importScripts() in den generierten Service Worker aufgenommen.

  • include

    (String | RegExp | Funktion)[] optional

    Mindestens ein Spezifizierer, mit dem Assets in das Precache-Manifest eingeschlossen werden. Dies wird nach denselben Regeln wie die Standardoption include von webpack interpretiert.

  • inlineWorkboxRuntime

    Boolescher Wert optional

    Standardwert ist: false

    Gibt an, ob der Laufzeitcode für die Workbox-Bibliothek im Service Worker der obersten Ebene enthalten oder in eine separate Datei aufgeteilt werden soll, die zusammen mit dem Service Worker bereitgestellt werden muss. Wenn Sie die Laufzeit getrennt halten, müssen Nutzer den Workbox-Code nicht jedes Mal neu herunterladen, wenn sich der Service Worker auf oberster Ebene ändert.

  • manifestEntries

    ManifestEntry[] optional

  • manifestTransforms

    ManifestTransform[] optional

    Eine oder mehrere Funktionen, die nacheinander auf das generierte Manifest angewendet werden. Wenn auch modifyURLPrefix oder dontCacheBustURLsMatching angegeben sind, werden die entsprechenden Transformationen zuerst angewendet.

  • maximumFileSizeToCacheInBytes

    Nummer optional

    Der Standardwert ist: 2097152

    Mit diesem Wert kann die maximale Größe von Dateien bestimmt werden, die vorab im Cache gespeichert werden. Dadurch wird verhindert, dass Sie versehentlich sehr große Dateien im Cache speichern, die versehentlich mit einem Ihrer Muster übereinstimmen.

  • Modus

    String optional

    Wenn dieser Wert auf „production“ gesetzt ist, wird ein optimiertes Service Worker-Bundle erstellt, das Debugging-Informationen ausschließt. Wenn hier nicht explizit konfiguriert, wird der in der aktuellen webpack-Kompilierung konfigurierte Wert mode verwendet.

  • modifyURLPrefix

    Objekt optional

    Ein Objekt, das Stringpräfixe Ersatzstringwerten zuordnet. So können Sie beispielsweise ein Pfadpräfix aus einem Manifesteintrag entfernen oder hinzufügen, wenn Ihre Webhosting-Einrichtung nicht mit der Einrichtung Ihres lokalen Dateisystems übereinstimmt. Als Alternative mit mehr Flexibilität können Sie die Option manifestTransforms verwenden und eine Funktion bereitstellen, die die Einträge im Manifest mit der von Ihnen angegebenen Logik ändert.

    Beispiel:

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

    String optional

    Standardwert: null

    Wenn angegeben, werden alle Navigationsanfragen für URLs, die nicht vorab im Cache gespeichert sind, mit dem HTML-Code unter der angegebenen URL erfüllt. Sie müssen die URL eines HTML-Dokuments übergeben, das in Ihrem Precache-Manifest aufgeführt ist. Diese Methode sollte in einem Szenario für die Single-Page-Anwendung verwendet werden, in dem alle Navigationen allgemeinen App Shell-HTML-Code verwenden sollen.

  • navigateFallbackAllowlist

    Regulärer Ausdruck[] optional

    Ein optionales Array regulärer Ausdrücke, das einschränkt, für welche URLs das konfigurierte Verhalten navigateFallback gilt. Das ist nützlich, wenn nur ein Teil der URLs deiner Website als Teil einer App mit nur einer Seite behandelt werden soll. Wenn sowohl navigateFallbackDenylist als auch navigateFallbackAllowlist konfiguriert sind, hat die Sperrliste Vorrang.

    Hinweis: Diese RegExps können während der Navigation mit jeder Ziel-URL ausgewertet werden. Vermeiden Sie die Verwendung komplexer RegExps, da Ihre Nutzer sonst möglicherweise Verzögerungen beim Navigieren auf Ihrer Website feststellen.

  • navigateFallbackDenylist

    Regulärer Ausdruck[] optional

    Ein optionales Array regulärer Ausdrücke, das einschränkt, für welche URLs das konfigurierte Verhalten navigateFallback gilt. Das ist nützlich, wenn nur ein Teil der URLs Ihrer Website als Teil einer App mit einer Seite behandelt werden soll. Wenn sowohl navigateFallbackDenylist als auch navigateFallbackAllowlist konfiguriert sind, hat die Sperrliste Vorrang.

    Hinweis: Diese RegExps können während der Navigation mit jeder Ziel-URL ausgewertet werden. Vermeiden Sie die Verwendung komplexer RegExps, da Ihre Nutzer sonst möglicherweise Verzögerungen beim Navigieren auf Ihrer Website feststellen.

  • navigationPreload

    Boolescher Wert optional

    Standardwert ist: false

    Gibt an, ob das Vorabladen der Navigation im generierten Service Worker aktiviert wird. Ist die Richtlinie auf „true“ gesetzt, müssen Sie außerdem runtimeCaching verwenden, um eine geeignete Antwortstrategie einzurichten, die Navigationsanfragen entspricht, und die vorab geladene Antwort zu verwenden.

  • offlineGoogleAnalytics

    Boolescher Wert | GoogleAnalyticsInitializeOptions optional

    Standardwert ist: false

    Legt fest, ob die Offline-Google Analytics-Version unterstützt werden soll. Bei true wird der Aufruf der initialize() von workbox-google-analytics dem generierten Service Worker hinzugefügt. Ist das Objekt auf Object gesetzt, wird es an den initialize()-Aufruf übergeben, sodass Sie das Verhalten anpassen können.

  • runtimeCaching

    RuntimeCaching[] optional

    Wenn Sie die Build-Tools von Workbox zum Generieren des Service Workers verwenden, können Sie eine oder mehrere Konfigurationen für das Laufzeit-Caching angeben. Diese werden dann mithilfe der von Ihnen definierten Abgleichs- und Handler-Konfiguration in workbox-routing.registerRoute-Aufrufe übersetzt.

    Informationen zu allen Optionen finden Sie in der Dokumentation zu workbox-build.RuntimeCaching. Das folgende Beispiel zeigt eine typische Konfiguration mit zwei definierten Laufzeitrouten:

  • skipWaiting

    Boolescher Wert optional

    Standardwert ist: false

    Gibt an, ob dem generierten Service Worker ein unbedingter Aufruf von skipWaiting() hinzugefügt wird. Bei false wird stattdessen ein message-Listener hinzugefügt, mit dem Clientseiten skipWaiting() durch Aufrufen von postMessage({type: 'SKIP_WAITING'}) für einen wartenden Service Worker auslösen können.

  • Sourcemap

    Boolescher Wert optional

    Standardwert: true

    Gibt an, ob eine Sourcemap für die generierten Service Worker-Dateien erstellt werden soll.

  • swDest

    String optional

    Der Standardwert ist "service-worker.js"

    Der Assetname der Service Worker-Datei, die von diesem Plug-in erstellt wurde.

InjectManifest

Diese Klasse unterstützt das Kompilieren einer über swSrc bereitgestellten Service Worker-Datei und das Einfügen einer Liste von URLs und Überarbeitungsinformationen für das Precaching in diesen Service Worker, die auf der Webpack-Asset-Pipeline basieren.

Verwenden Sie eine Instanz von InjectManifest im plugins-Array einer Webpack-Konfiguration.

Zusätzlich zum Einschleusen des Manifests führt dieses Plug-in eine Kompilierung der Datei swSrc durch und verwendet die Optionen aus der Haupt-Webpack-Konfiguration.

// 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: '...',
});

Attribute

  • Konstruktor

    void

    Erstellt eine Instanz von InjectManifest.

    Die Funktion constructor sieht so aus: 

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

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

Attribute

default

Typ

Objekt

Attribute

  • GenerateSW

    Abfrage

  • InjectManifest

    Abfrage