creazione-workbox

Il modulo workbox-build si integra in un processo di compilazione basato su nodi e può generare un intero service worker o solo un elenco di asset da prememorizzare nella cache 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 giuste da utilizzare.

Quale modalità utilizzare

generateSW

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

Quando utilizzarlo generateSW

  • Vuoi memorizzare nella cache preventiva i file.
  • Hai esigenze di memorizzazione nella cache del runtime semplici.

Quando NON utilizzarli generateSW

  • Vuoi utilizzare altre funzionalità di 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 genera un elenco di URL da memorizzare nella cache e aggiunge il manifest della cache a un file service worker esistente. In caso contrario, il file verrà lasciato invariato.

Quando utilizzarlo injectManifest

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

Quando NON utilizzarli 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 build basato su nodi, utilizzando le opzioni di configurazione più comuni, come segue:

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

Verrà generato un service worker con la configurazione del pre-caching per tutti i file selezionati dalla configurazione e le regole di memorizzazione nella cache del runtime fornite.

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

Modalità injectManifest

Puoi utilizzare la modalità injectManifest all'interno di uno script di build basato su nodi, utilizzando le opzioni di configurazione più comuni, come segue:

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

In questo modo, verrà creato un manifest di pre-cache basato sui file selezionati dalla configurazione e verrà inserito nel file service worker esistente.

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

Modalità aggiuntive

Prevediamo che generateSW o injectManifest soddisferanno 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

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

Puoi utilizzare la modalità injectManifest all'interno di uno script di build basato su nodi, utilizzando le opzioni di configurazione più comuni, come segue:

// 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 insieme completo di opzioni di configurazione è disponibile nella documentazione di riferimento.

Tipi

BasePartial

Proprietà

  • additionalManifestEntries

    (stringa | ManifestEntry)[] facoltativo

    Un elenco di voci da prememorizzare nella cache, oltre a quelle generate come parte della configurazione della build.

  • dontCacheBustURLsMatching

    RegExp (facoltativo)

    Gli asset corrispondenti verranno considerati con controllo delle versioni univoco tramite il loro URL ed esentati dal normale meccanismo di invalidazione della cache HTTP eseguito durante il popolamento della pre-cache. Sebbene non sia obbligatorio, è consigliabile che, se il processo di build esistente inserisce già un valore [hash] in ogni nome file, tu fornisca un'espressione regolare che lo rilevi, in quanto ridurrà la larghezza di banda consumata durante la prememorizzazione nella cache.

  • manifestTransforms

    ManifestTransform[] facoltativo

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

  • maximumFileSizeToCacheInBytes

    number optional

    Il valore predefinito è: 2097152

    Questo valore può essere utilizzato per determinare la dimensione massima dei file che verranno memorizzati nella cache. In questo modo, non memorizzerai nella cache inavvertitamente file di grandi dimensioni che potrebbero corrispondere accidentalmente a uno dei tuoi pattern.

  • modifyURLPrefix

    oggetto facoltativo

    Una stringa di mappatura degli oggetti con prefissi per i valori delle stringhe di sostituzione. Può essere utilizzato, ad esempio, per rimuovere o aggiungere un prefisso del percorso da una voce del manifest se la configurazione dell'hosting web non corrisponde alla configurazione del file system locale. In alternativa, per una maggiore flessibilità, puoi utilizzare l'opzione manifestTransforms e fornire una funzione che modifichi le voci nel manifest utilizzando la logica che preferisci.

    Esempio di utilizzo:

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

BuildResult

Tipo

Omit<GetManifestResult"manifestEntries"
> & object

Proprietà

  • filePaths

    string[]

GeneratePartial

Proprietà

  • babelPresetEnvTargets

    string[] facoltativo

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

    I target da passare a babel-preset-env durante la transpilazione del bundle del service worker.

  • cacheId

    stringa facoltativa

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

  • cleanupOutdatedCaches

    booleano facoltativo

    Il valore predefinito è: false

    Indica se Workbox deve tentare di identificare ed eliminare le precache 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 facoltativa

    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 corrispondenza con la cache. Deve essere impostato sul valore utilizzato dal server web per l'indice della directory.

  • disableDevLogs

    booleano facoltativo

    Il valore predefinito è: false

  • ignoreURLParametersMatching

    RegExp[] facoltativo

    I nomi dei parametri di ricerca che corrispondono a una delle espressioni regolari in questo array verranno rimossi prima di cercare una corrispondenza nella pre-cache. Ciò è utile se gli utenti potrebbero richiedere URL che contengono, ad esempio, parametri URL utilizzati per monitorare l'origine del traffico. Se non viene fornito, il valore predefinito è [/^utm_/, /^fbclid$/].

  • importScripts

    string[] facoltativo

    Un elenco di file JavaScript da passare a importScripts() all'interno del file service worker generato. Questa opzione è utile quando vuoi che Workbox crei il file service worker di primo livello, ma vuoi includere codice aggiuntivo, ad esempio un listener di eventi push.

  • inlineWorkboxRuntime

    booleano facoltativo

    Il valore predefinito è: false

    Indica se il codice di runtime per la libreria Workbox deve essere incluso nel service worker di primo livello o suddiviso in un file separato da implementare insieme al service worker. Mantenere separato il runtime significa che gli utenti non dovranno scaricare di nuovo il codice di Workbox ogni volta che cambia il service worker di primo livello.

  • modalità

    stringa facoltativa

    Il valore predefinito è: "production"

    Se è impostato su "production", verrà prodotto un bundle di service worker ottimizzato che esclude le informazioni di debug. Se non configurato esplicitamente qui, verrà utilizzato il valore process.env.NODE_ENV e, in caso contrario, verrà utilizzato 'production'.

  • navigateFallback

    stringa facoltativa

    Il valore predefinito è: null

    Se specificate, tutte le richieste di navigazione per gli URL non prememorizzati nella cache verranno soddisfatte con il codice HTML all'URL fornito. Devi trasmettere l'URL di un documento HTML elencato nel manifest della pre-cache. Questo deve essere utilizzato in uno scenario di app a pagina singola, in cui vuoi che tutte le navigazioni utilizzino un HTML App Shell comune.

  • navigateFallbackAllowlist

    RegExp[] facoltativo

    Un array facoltativo di espressioni regolari che limita gli URL a cui si applica il comportamento navigateFallback configurato. Ciò è utile se solo un sottoinsieme degli URL del tuo sito deve essere trattato come parte di un'app a una sola pagina. Se sono configurati sia navigateFallbackDenylist che navigateFallbackAllowlist, la denylist ha la precedenza.

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

  • navigateFallbackDenylist

    RegExp[] facoltativo

    Un array facoltativo di espressioni regolari che limita gli URL a cui si applica il comportamento navigateFallback configurato. Ciò è utile se solo un sottoinsieme degli URL del tuo sito deve essere trattato come parte di un'app a una sola pagina. Se sono configurati sia navigateFallbackDenylist sia navigateFallbackAllowlist, la denylist ha la precedenza.

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

  • navigationPreload

    booleano facoltativo

    Il valore predefinito è: false

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

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions facoltativo

    Il valore predefinito è: false

    Controlla se includere o meno il supporto per Google Analytics offline. Quando true, la chiamata a workbox-google-analytics's initialize() verrà aggiunta al service worker generato. Se impostato su un Object, questo 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 del runtime. Queste vengono poi tradotte in chiamate workbox-routing.registerRoute utilizzando la configurazione di corrispondenza e del 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 client di attivare skipWaiting() chiamando postMessage({type: 'SKIP_WAITING'}) su un service worker in attesa.

  • sourcemap

    booleano facoltativo

    Il valore predefinito è: true

    Indica se creare una mappa delle origini per i file service worker generati.

GenerateSWOptions

Tipo

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

Proprietà

  • conteggio

    numero

  • manifestEntries

    ManifestEntry[]

  • dimensioni

    numero

  • avvisi

    string[]

GlobPartial

Proprietà

  • globFollow

    booleano facoltativo

    Il valore predefinito è: true

    Determina se i link simbolici vengono seguiti durante la generazione del manifesto della precache. Per saperne di più, consulta la definizione di follow nella documentazione di glob.

  • globIgnores

    string[] facoltativo

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

    Un insieme di pattern che corrispondono ai file da escludere sempre durante la generazione del manifest di pre-cache. Per saperne di più, 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 manifest della pre-cache. Per saperne di più, consulta le nozioni di base su 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 stringa univoco. Le chiavi in questo oggetto sono URL sottoposti a rendering lato server. Se i valori sono un array di stringhe, verranno interpretati come pattern glob e i contenuti di tutti i file corrispondenti ai pattern verranno utilizzati per versionare in modo univoco l'URL. Se utilizzato con una singola stringa, verrà interpretato come informazioni di controllo delle versioni univoche che hai generato per un determinato URL.

InjectManifestOptions

Tipo

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

Proprietà

  • injectionPoint

    stringa facoltativa

    Il valore predefinito è: "self.__WB_MANIFEST"

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

  • swSrc

    stringa

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

ManifestEntry

Proprietà

  • integrità

    stringa facoltativa

  • revisione

    stringa

  • url

    stringa

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry & object)[],
  compilation?: unknown,
): Promise<ManifestTransformResult> | ManifestTransformResult

Tipo

funzione

Parametri

  • manifestEntries

    (ManifestEntry & object)[]

    • dimensioni

      numero

  • compilation

    sconosciuto facoltativo

Resi

ManifestTransformResult

Proprietà

  • manifest

    (ManifestEntry & object)[]

    • dimensioni

      numero

  • avvisi

    string[] facoltativo

OptionalGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa facoltativa

    La directory locale con cui vuoi confrontare globPatterns. Il percorso è relativo alla directory corrente.

RequiredGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa

    La directory locale con cui vuoi confrontare globPatterns. Il percorso è relativo alla directory corrente.

RequiredSWDestPartial

Proprietà

  • swDest

    stringa

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

RuntimeCaching

Proprietà

StrategyName

Enum

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

Tipo

BasePartial & WebpackPartial & GeneratePartial & WebpackGenerateSWPartial

WebpackGenerateSWPartial

Proprietà

  • importScriptsViaChunks

    string[] facoltativo

    Uno o più nomi di chunk webpack. Il contenuto di questi blocchi verrà incluso nel service worker generato tramite una chiamata a importScripts().

  • swDest

    stringa facoltativa

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

    Il nome dell'asset del file service worker creato da questo plug-in.

WebpackInjectManifestOptions

Tipo

BasePartial & WebpackPartial & InjectPartial & WebpackInjectManifestPartial

WebpackInjectManifestPartial

Proprietà

  • compileSrc

    booleano facoltativo

    Il valore predefinito è: true

    Se true (impostazione predefinita), il file swSrc verrà compilato da webpack. Quando false, la compilazione non verrà eseguita (e webpackCompilationPlugins non può essere utilizzato). Imposta su false se vuoi inserire il manifest in, ad esempio, un file JSON.

  • swDest

    stringa facoltativa

    Il nome dell'asset del file service worker che verrà creato da questo plug-in. Se omesso, il nome si baserà sul nome di 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à

  • pezzi

    string[] facoltativo

    Uno o più nomi di chunk i cui file di output corrispondenti devono essere inclusi nel manifest di pre-cache.

  • escludi

    (string | RegExp | function)[] facoltativo

    Uno o più specificatori utilizzati per escludere le risorse dal manifest di pre-cache. Viene interpretato seguendo le stesse regole dell'opzione standard exclude di webpack. Se non viene fornito, il valore predefinito è [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] facoltativo

    Uno o più nomi di chunk i cui file di output corrispondenti devono essere esclusi dal manifest di pre-cache.

  • includi

    (string | RegExp | function)[] facoltativo

    Uno o più specificatori utilizzati per includere gli asset nel manifest di pre-cache. Viene interpretato seguendo le stesse regole dell'opzione standard include di webpack.

  • modalità

    stringa facoltativa

    Se è impostato su "production", verrà prodotto un bundle di service worker ottimizzato che esclude le informazioni di debug. Se non configurato esplicitamente qui, verrà utilizzato il valore mode configurato nella compilazione webpack corrente.

Metodi

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
): Promise<string>

In questo modo viene copiato un insieme di librerie di runtime utilizzate da Workbox in una directory locale, che deve essere implementata insieme al file service worker.

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

Questo metodo è esposto a vantaggio degli sviluppatori che utilizzano workbox-build.injectManifest e che preferiscono 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 principale in cui verrà creata la nuova directory delle librerie.

Resi

  • Promise<string>

    Il nome della directory appena creata.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
): Promise<BuildResult>

Questo metodo crea un elenco di URL da prememorizzare nella cache, chiamato "manifesto di prememorizzazione nella cache", in base alle opzioni che fornisci.

Accetta anche opzioni aggiuntive che configurano il comportamento del service worker, ad esempio le regole runtimeCaching da utilizzare.

In base al manifest di pre-cache e alla configurazione aggiuntiva, scrive un file service worker pronto all'uso su disco in 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

Resi

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
): Promise<GetManifestResult>

Questo metodo restituisce un elenco di URL da prememorizzare nella cache, denominato "manifesto precache", insieme ai dettagli sul numero di voci e sulle loro dimensioni, in base alle opzioni che fornisci.

// 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

Resi

getModuleURL()

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

Parametri

  • moduleName

    stringa

  • buildType

    BuildType

Resi

  • stringa

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

Questo metodo crea un elenco di URL da prememorizzare nella cache, chiamato "manifesto di prememorizzazione nella cache", in base alle opzioni che fornisci.

Il manifest viene inserito nel file swSrc e la stringa segnaposto injectionPoint determina la posizione in cui deve essere inserito il manifest nel file.

Il file service worker finale, con il manifest iniettato, viene scritto su disco in swDest.

Questo metodo non compila né raggruppa il file swSrc, ma gestisce solo 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

Resi