creazione-workbox

Il modulo workbox-build si integra in un processo di compilazione basato su nodi e può generare un intero service worker o semplicemente generare un elenco di asset da precache che potrebbero essere utilizzati all'interno di un service worker esistente.

Le due modalità che la maggior parte degli sviluppatori utilizzerà sono generateSW e injectManifest. Le risposte alle seguenti domande possono aiutarti a scegliere la modalità e la configurazione giusta da utilizzare.

Modalità da usare

generateSW

La modalità generateSW crea per te un file del service worker, personalizzato tramite le opzioni di configurazione, e lo scrive su disco.

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

La modalità injectManifest genererà un elenco di URL da pre-cache e aggiungerà il manifest di questa 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.

Modalità generateSW

Puoi utilizzare la modalità generateSW all'interno di uno script di compilazione basato su nodo, utilizzando le opzioni di configurazione più comuni, ad esempio:

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

Questo genererà un service worker con una configurazione di pre-memorizzazione nella cache per tutti i file selezionati 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.

Modalità injectManifest

Puoi utilizzare la modalità injectManifest all'interno di uno script di compilazione basato su nodo, utilizzando le opzioni di configurazione più comuni, ad esempio:

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

Verrà creato un manifest di pre-cache in base ai file selezionati dalla configurazione e il file verrà inserito nel file del service worker esistente.

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

Modalità aggiuntive

Prevediamo che generateSW o injectManifest soddisfino le esigenze della maggior parte degli sviluppatori. Tuttavia, esiste un'altra modalità supportata da workbox-build che potrebbe essere appropriata per determinati casi d'uso.

Modalità getManifest

È concettualmente simile alla modalità injectManifest, ma invece di aggiungere il manifest al file del service worker di origine, restituisce l'array di voci manifest, insieme alle informazioni sul numero di voci e sulle dimensioni totali.

Puoi utilizzare la modalità injectManifest all'interno di uno script di compilazione basato su nodo, utilizzando le opzioni di configurazione più comuni, ad esempio:

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

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

Tipi

BasePartial

Proprietà

  • additionalManifestEntries

    (stringa | ManifestEntry)[] facoltativo

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

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

  • manifestTransforms

    ManifestTransform[] facoltativo

    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.

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

BuildResult

Tipo

Ometti <GetManifestResult"manifestEntries"
> e oggetto

Proprietà

  • filePaths

    stringa[]

GeneratePartial

Proprietà

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

  • 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

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

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

  • modalità

    stringa facoltativo

    Il valore predefinito è: "production"

    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 process.env.NODE_ENV; in caso contrario, verrà utilizzato il valore 'production'.

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

GenerateSWOptions

Tipo

BasePartial e GlobPartial e GeneratePartial e RequiredSWDestPartial e OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial & GlobPartial e RequiredGlobDirectoryPartial

GetManifestResult

Proprietà

  • count

    numero

  • manifestEntries

    ManifestEntry[]

  • dimensioni

    numero

  • avvisi

    stringa[]

GlobPartial

Proprietà

  • globFollow

    booleano facoltativo

    Il valore predefinito è: true

    Determina se i link simbolici vengono seguiti o meno durante la generazione del manifest di precache. Per ulteriori informazioni, consulta la definizione di follow nella documentazione di glob.

  • globIgnores

    string[] facoltativo

    Il valore predefinito è: ["**\/node_modules\/**\/*"]

    Un insieme di pattern corrispondenti ai file da escludere sempre durante la generazione del manifest di preregistrazione. Per ulteriori informazioni, consulta la definizione di ignore nella documentazione di glob.

  • globPatterns

    string[] facoltativo

    Il valore predefinito è: ["**\/*.{js,wasm,css,html}"]

    I file che corrispondono a uno qualsiasi di questi pattern verranno inclusi nel file manifest precache. Per ulteriori informazioni, consulta la glob.

  • globStrict

    booleano facoltativo

    Il valore predefinito è: true

    Se il valore è true, un errore durante la lettura di una directory durante la generazione di un manifest precache comporterà l'errore della build. Se il valore è false, la directory problematica verrà saltata. Per ulteriori informazioni, consulta la definizione di strict nella documentazione di glob.

  • templatedURLs

    oggetto facoltativo

    Se un URL viene visualizzato in base a una logica lato server, i suoi contenuti potrebbero dipendere da più file o da un altro valore di stringa univoco. Le chiavi in questo oggetto sono URL sottoposti a rendering dal server. Se i valori sono un array di stringhe, verranno interpretati come pattern glob e i contenuti di tutti i file che corrispondono ai pattern verranno utilizzati per creare una versione univoca dell'URL. Se utilizzata con una singola stringa, verrà interpretata come informazioni univoche sul controllo delle versioni che hai generato per un determinato URL.

InjectManifestOptions

Tipo

BasePartial & GlobPartial & InjectPartial e RequiredSWDestPartial e RequiredGlobDirectoryPartial

InjectPartial

Proprietà

  • injectionPoint

    stringa facoltativo

    Il valore predefinito è: "self.__WB_MANIFEST"

    La stringa da trovare all'interno del file swSrc. Una volta trovato, verrà sostituito dal manifest di precache generato.

  • swSrc

    stringa

    Il percorso e il nome file del file del service worker che verrà letto durante il processo di compilazione, in relazione alla directory di lavoro corrente.

ManifestEntry

Proprietà

  • integrità

    stringa facoltativo

  • revisione

    stringa

  • url

    stringa

ManifestTransform()

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

Tipo

funzione

Parametri

  • manifestEntries

    (ManifestEntry e oggetto)[]

    • dimensioni

      numero

  • compilazione

    sconosciuto facoltativo

Ritorni

ManifestTransformResult

Proprietà

  • manifest

    (ManifestEntry e oggetto)[]

    • dimensioni

      numero

  • avvisi

    string[] facoltativo

OptionalGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa facoltativo

    La directory locale con cui vuoi trovare corrispondenze di globPatterns. Il percorso è relativo alla directory attuale.

RequiredGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa

    La directory locale con cui vuoi trovare corrispondenze di globPatterns. Il percorso è relativo alla directory attuale.

RequiredSWDestPartial

Proprietà

  • swDest

    stringa

    Il percorso e il nome file del file del service worker che verrà creato dal processo di compilazione, in relazione alla directory di lavoro corrente. Deve terminare con ".js".

RuntimeCaching

Proprietà

StrategyName

Enum

"CacheFirst"

"NetworkFirst"

WebpackGenerateSWOptions

Tipo

BasePartial e WebpackPartial e GeneratePartial e WebpackGenerateSWPartial,

WebpackGenerateSWPartial

Proprietà

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

  • swDest

    stringa facoltativo

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

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

WebpackInjectManifestOptions

Tipo

BasePartial e WebpackPartial e InjectPartial e WebpackInjectManifestPartial

WebpackInjectManifestPartial

Proprietà

  • compileSrc

    booleano facoltativo

    Il valore predefinito è: true

    Quando true (valore predefinito), il file swSrc verrà compilato dal webpack. Se false, la compilazione non verrà eseguita (e non è possibile utilizzare webpackCompilationPlugins). Imposta il valore false se vuoi inserire il manifest, ad esempio in un file JSON.

  • swDest

    stringa facoltativo

    Il nome asset del file del service worker che verrà creato dal plug-in. Se omesso, si baserà sul nome swSrc.

  • webpackCompilationPlugins

    any[] facoltativo

    Plug-in webpack facoltativi che verranno utilizzati durante la compilazione del file di input swSrc. Valido solo se compileSrc è true.

WebpackPartial

Proprietà

  • blocchi

    string[] facoltativo

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

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

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

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

Metodi

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

Viene copiato un insieme di librerie di runtime utilizzate da Workbox in una directory locale, di cui deve essere eseguito il deployment insieme al file del service worker.

In alternativa al deployment di queste copie locali, puoi utilizzare Workbox dell'URL CDN ufficiale.

Questo metodo è esposto a vantaggio degli sviluppatori che utilizzano workbox-build.injectManifest che preferirebbero non utilizzare le copie CDN di Workbox. Gli sviluppatori che utilizzano workbox-build.generateSW non devono chiamare esplicitamente questo metodo.

Parametri

  • destDirectory

    stringa

    Il percorso della directory padre in cui verrà creata la nuova directory di librerie.

Ritorni

  • Promessa<string>

    Il nome della directory appena creata.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

Questo metodo crea un elenco di URL da pre-cache, denominato "manifest di pre-cache", in base alle opzioni fornite.

Prende anche opzioni aggiuntive che configurano il comportamento del service worker, come le eventuali regole runtimeCaching che dovrebbe utilizzare.

In base al manifest di pre-cache e alla configurazione aggiuntiva, scrive un file del service worker pronto all'uso su disco all'indirizzo 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: '...',
});

Parametri

Ritorni

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
)

Questo metodo restituisce un elenco di URL da pre-cache, definito "manifest precache" insieme a dettagli sul numero di voci e sulle relative dimensioni, in base alle opzioni fornite.

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

Parametri

Ritorni

getModuleURL()

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

Parametri

  • moduleName

    stringa

  • buildType

    BuildType

Ritorni

  • stringa

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

Questo metodo crea un elenco di URL da pre-cache, denominato "manifest di pre-cache", in base alle opzioni fornite.

Il manifest viene inserito nel file swSrc e la stringa segnaposto injectionPoint determina la posizione all'interno del file.

Il file finale del service worker, con il manifest inserito, viene scritto sul disco in swDest.

Questo metodo non compila né raggruppa il file swSrc, ma si limita a gestire l'inserimento del manifest.

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

Parametri

Ritorni