workbox-webpack-plugin

Workbox fornisce due plug-in webpack: uno che genera un service worker completo e uno che genera un elenco di asset da pre-cache che vengono inseriti in un file del service worker.

I plug-in vengono implementati in due classi nel modulo workbox-webpack-plugin, denominate GenerateSW e InjectManifest. Le risposte alle seguenti domande possono aiutarti a scegliere il plug-in e la configurazione giusti da utilizzare.

Plug-in da usare

GenerateSW

Il plug-in GenerateSW creerà un file del service worker per te e lo aggiungerà alla pipeline degli asset Webpack.

Quando utilizzare GenerateSW

  • Vuoi pre-memorizzare i file nella cache.
  • Hai esigenze semplici per la memorizzazione nella cache di runtime.

Quando NON utilizzare GenerateSW

  • Vuoi utilizzare altre funzionalità dei service worker (ad es. Web push).
  • Vuoi importare script aggiuntivi o aggiungere logica aggiuntiva per strategie di memorizzazione nella cache personalizzate.

InjectManifest

Il plug-in InjectManifest genererà un elenco di URL da pre-cache e aggiungerà il manifest di pre-cache a un file del service worker esistente. In caso contrario, il file rimarrà invariato.

Quando utilizzare InjectManifest

  • Vuoi un maggiore controllo sul service worker.
  • Vuoi pre-memorizzare i file nella cache.
  • Devi personalizzare il routing e le strategie.
  • Vuoi utilizzare il service worker con altre funzionalità della piattaforma (ad es. Web Push).

Quando NON utilizzare InjectManifest

  • Vuoi il percorso più semplice per aggiungere un service worker al tuo sito.

Plug-in GeneraSW

Puoi aggiungere il plug-in GenerateSW alla configurazione del webpack nel seguente modo:

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

Questo genererà un service worker con una configurazione di precaching per tutte le risorse webpack selezionate dalla tua configurazione e le regole di memorizzazione nella cache di runtime fornite.

Un set completo di opzioni di configurazione è disponibile nella documentazione di riferimento.

Plug-in InjectManifest

Puoi aggiungere il plug-in InjectManifest alla configurazione del webpack nel seguente modo:

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

Verrà creato un manifest di pre-cache basato sulle risorse del webpack selezionate dalla tua configurazione e verrà inserito nel file del service worker in bundle e compilato.

Un set completo di opzioni di configurazione è disponibile nella documentazione di riferimento.

Ulteriori informazioni

Le indicazioni sull'utilizzo dei plug-in nel contesto di una build webpack più grande sono disponibili nella sezione "Progressive Web Application" della documentazione del webpack.

Tipi

GenerateSW

Questa classe supporta la creazione di un nuovo file del service worker pronto all'uso come parte del processo di compilazione del webpack.

Utilizza un'istanza di GenerateSW nell'array plugins di una configurazione di webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

Proprietà

GenerateSWConfig

Proprietà

  • additionalManifestEntries

    (string | ManifestEntry)[] facoltativo

    Un elenco di voci da pre-cache da memorizzare nella cache, oltre a quelle generate nell'ambito della configurazione della build.

  • babelPresetEnvTargets

    string[] facoltativo

    Il valore predefinito è: ["chrome >= 56"]

    I target da passare a babel-preset-env durante il transpiling del bundle del service worker.

  • cacheId

    stringa facoltativo

    Un ID facoltativo da anteporre ai nomi della cache. Questo è utile principalmente per lo sviluppo locale in cui possono essere pubblicati più siti dalla stessa origine http://localhost:port.

  • blocchi

    string[] facoltativo

    Uno o più nomi di blocchi i cui file di output corrispondenti devono essere inclusi nel manifest precache.

  • cleanupOutdatedCaches

    booleano facoltativo

    Il valore predefinito è: false

    Indica se Workbox deve tentare di identificare ed eliminare eventuali pre-cache create da versioni precedenti e incompatibili.

  • clientsClaim

    booleano facoltativo

    Il valore predefinito è: false

    Indica se il service worker deve iniziare a controllare i client esistenti non appena viene attivato.

  • directoryIndex

    stringa facoltativo

    Se una richiesta di navigazione per un URL che termina con / non corrisponde a un URL memorizzato nella cache, questo valore verrà aggiunto all'URL e verrà verificata la presenza di una corrispondenza precache. Deve essere impostato su quello utilizzato dal server web per l'indice di directory.

  • disableDevLogs

    booleano facoltativo

    Il valore predefinito è: false

  • dontCacheBustURLsMatching

    Espressione regolare facoltativa

    Gli asset che corrispondono a questa condizione verranno presupposti in modo univoco per il controllo delle versioni tramite il relativo URL ed esenti dal normale busting della cache HTTP che viene eseguito durante la compilazione della pre-cache. Anche se non è obbligatorio, è consigliabile che se il processo di compilazione esistente inserisce già un valore [hash] in ogni nome file, devi fornire un'espressione regolare che lo rileverà, in quanto ridurrà la larghezza di banda consumata per la pre-memorizzazione nella cache.

  • escludi

    (stringa | RegExp | function)[] facoltativo

    Uno o più specificatiri utilizzati per escludere gli asset dal file manifest precache. Questo viene interpretato in base alle stesse regole dell'opzione exclude standard di webpack. Se non viene specificato, il valore predefinito è [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] facoltativo

    Uno o più nomi di blocchi i cui file di output corrispondenti devono essere esclusi dal file manifest precache.

  • ignoreURLParametersMatching

    RegExp[] facoltativo

    Tutti i nomi dei parametri di ricerca che corrispondono a una delle RegExp in questo array verranno rimossi prima di cercare una corrispondenza precache. Questo è utile se gli utenti potrebbero richiedere URL contenenti, ad esempio, parametri URL utilizzati per monitorare la sorgente del traffico. Se non viene specificato, il valore predefinito è [/^utm_/, /^fbclid$/].

  • importScripts

    string[] facoltativo

    Un elenco di file JavaScript che devono essere passati a importScripts() all'interno del file del service worker generato. Questo è utile quando vuoi consentire a Workbox di creare il file del service worker di primo livello, ma vuoi includere del codice aggiuntivo, ad esempio un listener di eventi push.

  • importScriptsViaChunks

    string[] facoltativo

    Uno o più nomi di blocchi di webpack. I contenuti di questi blocchi saranno inclusi nel service worker generato, tramite una chiamata a importScripts().

  • includi

    (stringa | RegExp | function)[] facoltativo

    Uno o più specificatiri utilizzati per includere gli asset nel file manifest precache. Questo viene interpretato in base alle stesse regole dell'opzione include standard di webpack.

  • inlineWorkboxRuntime

    booleano facoltativo

    Il valore predefinito è: false

    Indica se il codice runtime per la libreria Workbox deve essere incluso nel service worker di primo livello o suddiviso in un file separato di cui deve essere eseguito il deployment insieme al service worker. Mantenendo separato il runtime, gli utenti non dovranno scaricare nuovamente il codice di Workbox ogni volta che cambia il service worker di primo livello.

  • manifestEntries

    Facoltativo ManifestEntry[]

  • manifestTransforms

    Facoltativo ManfestTransform[]

    Una o più funzioni che verranno applicate in sequenza al manifest generato. Se sono specificati anche modifyURLPrefix o dontCacheBustURLsMatching, le trasformazioni corrispondenti verranno applicate per prime.

  • maximumFileSizeToCacheInBytes

    numero facoltativo

    Il valore predefinito è: 2097152

    Questo valore può essere utilizzato per determinare la dimensione massima dei file che verranno prememorizzati nella cache. In questo modo puoi impedire inavvertitamente la memorizzazione nella cache di file molto grandi che potrebbero aver accidentalmente trovato una corrispondenza con uno dei tuoi pattern.

  • modalità

    stringa facoltativo

    Se impostato su "produzione", verrà generato un bundle del service worker ottimizzato che esclude le informazioni di debug. Se non viene configurato esplicitamente qui, verrà utilizzato il valore mode configurato nell'attuale compilazione di webpack.

  • modifyURLPrefix

    oggetto facoltativo

    Una stringa di mappatura degli oggetti ha come prefisso i valori di stringa sostitutivi. È possibile utilizzarlo, ad esempio, per rimuovere o aggiungere un prefisso di percorso da una voce manifest se la configurazione dell'hosting web non corrisponde a quella del file system locale. In alternativa, con maggiore flessibilità, puoi utilizzare l'opzione manifestTransforms e fornire una funzione che modifichi le voci nel manifest utilizzando qualsiasi logica tu fornisca.

    Esempio di utilizzo:

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

    stringa facoltativo

    Il valore predefinito è: null

    Se specificato, tutte le richieste di navigazione per gli URL non prememorizzati nella cache verranno soddisfatte con il codice HTML dell'URL fornito. Devi trasmettere l'URL di un documento HTML elencato nel file manifest pre-cache. Questo deve essere utilizzato in uno scenario di app a pagina singola in cui tutte le navigazioni devono utilizzare l'HTML della shell dell'app comune.

  • navigateFallbackAllowlist

    RegExp[] facoltativo

    Un array facoltativo di espressioni regolari che limita gli URL a cui si applica il comportamento di navigateFallback configurato. Questo è utile se solo un sottoinsieme di URL del tuo sito deve essere trattato come parte di un'app a pagina singola. Se navigateFallbackDenylist e navigateFallbackAllowlist sono configurati, la lista bloccata ha la precedenza.

    Nota: queste espressioni regolari possono essere valutate in base a ogni URL di destinazione durante una navigazione. Evita di utilizzare RegExp complesse, altrimenti gli utenti potrebbero riscontrare ritardi durante la navigazione sul sito.

  • navigateFallbackDenylist

    RegExp[] facoltativo

    Un array facoltativo di espressioni regolari che limita gli URL a cui si applica il comportamento di navigateFallback configurato. Questo è utile se solo un sottoinsieme di URL del tuo sito deve essere trattato come parte di un'app a pagina singola. Se navigateFallbackDenylist e navigateFallbackAllowlist sono configurati, la lista bloccata ha la precedenza.

    Nota: queste espressioni regolari possono essere valutate in base a ogni URL di destinazione durante una navigazione. Evita di utilizzare RegExp complesse, altrimenti gli utenti potrebbero riscontrare ritardi durante la navigazione sul sito.

  • navigationPreload

    booleano facoltativo

    Il valore predefinito è: false

    Indica se abilitare o meno il precaricamento della navigazione nel service worker generato. Se questo criterio viene impostato su true, devi utilizzare anche runtimeCaching per configurare una strategia di risposta appropriata che corrisponda alle richieste di navigazione e utilizzare la risposta precaricata.

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions facoltativo

    Il valore predefinito è: false

    Consente di stabilire se includere o meno il supporto per Google Analytics offline. Quando true, la chiamata al initialize() di workbox-google-analytics verrà aggiunta al service worker generato. Se impostato su Object, l'oggetto verrà passato alla chiamata initialize(), consentendoti di personalizzare il comportamento.

  • runtimeCaching

    RuntimeCaching[] facoltativo

    Quando utilizzi gli strumenti di compilazione di Workbox per generare il service worker, puoi specificare una o più configurazioni di memorizzazione nella cache di runtime. Questi vengono poi tradotti in chiamate workbox-routing.registerRoute utilizzando la configurazione di corrispondenza e gestore che definisci.

    Per tutte le opzioni, consulta la documentazione di workbox-build.RuntimeCaching. L'esempio seguente mostra una configurazione tipica, con due route di runtime definite:

  • skipWaiting

    booleano facoltativo

    Il valore predefinito è: false

    Se aggiungere una chiamata incondizionata a skipWaiting() al service worker generato. Se false, verrà aggiunto un listener message, che consente alle pagine del client di attivare skipWaiting() chiamando postMessage({type: 'SKIP_WAITING'}) su un service worker in attesa.

  • mappa di origine

    booleano facoltativo

    Il valore predefinito è: true

    Se creare una mappa di origine per i file dei service worker generati.

  • swDest

    stringa facoltativo

    Il valore predefinito è: "service-worker.js"

    Il nome asset del file del service worker creato dal plug-in.

InjectManifest

Questa classe supporta la compilazione di un file del service worker fornito tramite swSrc e l'inserimento nel service worker di un elenco di URL e di informazioni sulle revisioni per la pre-cache in base alla pipeline degli asset webpack.

Utilizza un'istanza di InjectManifest nell'array plugins di una configurazione di webpack.

Oltre a inserire il manifest, questo plug-in eseguirà una compilazione del file swSrc, utilizzando le opzioni della configurazione principale del webpack.

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

Proprietà

  • costruttore

    void

    Crea un'istanza di InjectManifest.

    La funzione constructor ha il seguente aspetto: 

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

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

Proprietà

default

Tipo

oggetto

Proprietà

  • GenerateSW

    query

  • InjectManifest

    query