creazione-workbox

Il modulo workbox-build si integra in un processo di compilazione basato su Node e può generare un intero service worker o semplicemente un elenco di asset da memorizzare nella cache in modo da poter essere utilizzati in 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 di worker di servizio personalizzato tramite le opzioni di configurazione e lo scrive su disco.

Quando utilizzare generateSW

  • Vuoi eseguire la memorizzazione nella cache dei file.
  • Hai esigenze di memorizzazione nella cache di runtime semplici.

Quando NON utilizzare generateSW

  • Vuoi utilizzare altre funzionalità di Service Worker (ad es. push web).
  • Vuoi importare script aggiuntivi o aggiungere logica aggiuntiva per le strategie di memorizzazione nella cache personalizzata.

injectManifest

La modalità injectManifest genera un elenco di URL da memorizzare nella cache e aggiunge il manifest della cache a un file di service worker esistente. In caso contrario, il file rimarrà invariato.

Quando utilizzare injectManifest

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

Quando NON utilizzare injectManifest

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

Modalità generateSW

Puoi utilizzare la modalità generateSW all'interno di uno script di compilazione basato su Node, 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 worker di servizio con la configurazione del pre-caching per tutti i file rilevati dalla configurazione e le regole di memorizzazione nella cache di 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 compilazione basato su Node, 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.`);
});

Verrà creato un manifest precache in base ai file rilevati dalla configurazione e verrà inserito nel file del servizio 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

È concettualmente simile alla modalità injectManifest, ma anziché aggiungere il manifest al file del servizio 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 Node, 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 precache, oltre a eventuali voci generate nell'ambito della configurazione della build.

  • dontCacheBustURLsMatching

    Facoltativo RegExp

    Per gli asset corrispondenti a questo valore si presume che abbiano una versione univoca tramite il loro URL e che siano esenti dalla normale eliminazione della cache HTTP eseguita durante il completamento della precache. Sebbene non sia obbligatorio, se il tuo processo di compilazione esistente inserisce già un valore [hash] in ogni nome file, ti consigliamo di fornire un'espressione regolare che lo rileverà, in quanto ridurrà la larghezza di banda consumata durante il pre-caching.

  • manifestTransforms

    ManifestTransform[] facoltativo

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

  • maximumFileSizeToCacheInBytes

    number facoltativo

    Il valore predefinito è: 2097152

    Questo valore può essere utilizzato per determinare le dimensioni massime dei file che verranno precaricati. In questo modo, eviterai di eseguire il pre-caching inavvertitamente di file molto grandi che potrebbero corrispondere accidentalmente a uno dei tuoi pattern.

  • modifyURLPrefix

    Oggetto facoltativo

    Un oggetto che mappa i prefissi di stringa ai valori delle stringhe di sostituzione. Può essere utilizzato, ad esempio, per rimuovere o aggiungere un prefisso di percorso da una voce manifest se la configurazione dell'hosting web non corrisponde alla configurazione del file system locale. Come alternativa più flessibile, puoi utilizzare l'opzione manifestTransforms e fornire una funzione che modifichi le voci nel file 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

Ometti<GetManifestResult"manifestEntries"
> & oggetto

Proprietà

  • filePaths

    stringa[]

GeneratePartial

Proprietà

  • babelPresetEnvTargets

    stringa[] facoltativo

    Valore predefinito: ["chrome >= 56"]

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

  • cacheId

    stringa facoltativa

    Un ID facoltativo da anteporre ai nomi della cache. Questa opzione è utile principalmente per lo sviluppo locale, in cui è possibile pubblicare più siti dalla stessa originehttp://localhost:port.

  • cleanupOutdatedCaches

    booleano facoltativo

    Valore predefinito: false

    Se Workbox deve tentare di identificare ed eliminare eventuali precache creati da versioni precedenti incompatibili.

  • clientsClaim

    booleano facoltativo

    Valore predefinito: false

    Indica se il worker del servizio deve iniziare a controllare qualsiasi client esistente non appena si attiva.

  • directoryIndex

    stringa facoltativa

    Se una richiesta di navigazione per un URL che termina con / non corrisponde a un URL precompilato, questo valore verrà aggiunto all'URL e verrà controllato se esiste una corrispondenza precompilata. Deve essere impostato sul valore utilizzato dal server web per l'indice della directory.

  • disableDevLogs

    booleano facoltativo

    Valore predefinito: false

  • ignoreURLParametersMatching

    RegExp[] facoltativo

    Tutti i nomi dei parametri di ricerca che corrispondono a una delle espressioni regolari in questo array verranno rimossi prima di cercare una corrispondenza di precache. Questa opzione è 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

    stringa[] facoltativo

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

  • inlineWorkboxRuntime

    booleano facoltativo

    Valore predefinito: false

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

  • modalità

    stringa facoltativa

    Valore predefinito: "production"

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

  • navigateFallback

    stringa facoltativa

    Valore predefinito: null

    Se specificato, tutte le richieste di navigazione per gli URL che non sono memorizzati nella cache verranno soddisfatte con il codice HTML all'URL fornito. Devi passare l'URL di un documento HTML elencato nel manifest precache. Questo codice è pensato per 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 viene applicato il comportamento navigateFallback configurato. Questo è utile se solo un insieme di URL del tuo sito deve essere considerato parte di un'app a pagina singola. Se sono configurati sia navigateFallbackDenylist sia navigateFallbackAllowlist, ha la precedenza la lista di rifiuto.

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

  • navigateFallbackDenylist

    RegExp[] facoltativo

    Un array facoltativo di espressioni regolari che limita gli URL a cui viene applicato il comportamento navigateFallback configurato. Questa opzione è utile se solo un sottoinsieme di URL del tuo sito deve essere considerato parte di un'app a pagina singola. Se sono configurati sia navigateFallbackDenylist sia navigateFallbackAllowlist, la lista di esclusione ha la precedenza.

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

  • navigationPreload

    booleano facoltativo

    Valore predefinito: false

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

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions facoltativo

    Valore predefinito: false

    Controlla se includere o meno il supporto per Google Analytics offline. Quando true, la chiamata a initialize() di workbox-google-analytics verrà aggiunta al tuo 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 tuo worker di servizio, puoi specificare una o più configurazioni di memorizzazione nella cache in fase di runtime. Queste vengono poi tradotte in chiamate workbox-routing.registerRoute utilizzando la configurazione di corrispondenza e di 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 definiti:

  • skipWaiting

    booleano facoltativo

    Valore predefinito: false

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

  • sourcemap

    booleano facoltativo

    Valore predefinito: true

    Indica se creare un file sourcemap per i file del service worker generati.

GenerateSWOptions

Tipo

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial e GlobPartial e RequiredGlobDirectoryPartial

GetManifestResult

Proprietà

  • conteggio

    numero

  • manifestEntries

    ManifestEntry[]

  • dimensioni

    numero

  • avvisi

    stringa[]

GlobPartial

Proprietà

  • globFollow

    booleano facoltativo

    Valore predefinito: true

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

  • globIgnores

    stringa[] facoltativo

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

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

  • globPatterns

    stringa[] facoltativo

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

    I file corrispondenti a uno di questi pattern verranno inclusi nel manifest precache. Per ulteriori informazioni, consulta la globguida introduttiva.

  • globStrict

    booleano facoltativo

    Valore predefinito: true

    Se true, un errore di lettura di una directory durante la generazione di un manifest precache causerà il fallimento della compilazione. Se è falso, 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 relativi contenuti possono dipendere da più file o da un altro valore di stringa univoco. Le chiavi di questo oggetto sono URL visualizzati sul 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 generare una versione univoca dell'URL. Se utilizzato con una singola stringa, verrà interpretato come informazioni di versionamento univoche generate per un determinato URL.

InjectManifestOptions

Tipo

BasePartial & GlobPartial & InjectPartial & RequiredSWDestPartial & RequiredGlobDirectoryPartial

InjectPartial

Proprietà

  • injectionPoint

    stringa facoltativa

    Valore predefinito: "self.__WB_MANIFEST"

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

  • swSrc

    stringa

    Il percorso e il nome del file del servizio worker che verrà letto durante il processo di compilazione, rispetto 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

    unknown facoltativo

Resi

ManifestTransformResult

Proprietà

  • manifest

    (ManifestEntry & object)[]

    • dimensioni

      numero

  • avvisi

    stringa[] facoltativo

OptionalGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa facoltativa

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

RequiredGlobDirectoryPartial

Proprietà

  • globDirectory

    stringa

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

RequiredSWDestPartial

Proprietà

  • swDest

    stringa

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

RuntimeCaching

Proprietà

StrategyName

Enum

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

WebpackGenerateSWOptions

Tipo

BasePartial e WebpackPartial e GeneratePartial e WebpackGenerateSWPartial

WebpackGenerateSWPartial

Proprietà

  • importScriptsViaChunks

    stringa[] facoltativo

    Uno o più nomi di chunk webpack. I contenuti di questi chunk verranno inclusi nel servizio worker generato tramite una chiamata a importScripts().

  • swDest

    stringa facoltativa

    Valore predefinito: "service-worker.js"

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

WebpackInjectManifestOptions

Tipo

BasePartial e WebpackPartial e InjectPartial e WebpackInjectManifestPartial

WebpackInjectManifestPartial

Proprietà

  • compileSrc

    booleano facoltativo

    Valore predefinito: true

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

  • swDest

    stringa facoltativa

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

    stringa[] facoltativo

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

  • escludi

    (stringa | RegExp | funzione)[] facoltativo

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

  • excludeChunks

    stringa[] facoltativo

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

  • includi

    (stringa | RegExp | funzione)[] facoltativo

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

  • modalità

    stringa facoltativa

    Se impostato su "production", verrà prodotto un bundle di worker di servizio 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 del tuo worker di servizio.

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

Questo metodo è esposto a beneficio degli sviluppatori che utilizzano workbox-build.injectManifest e 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 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 memorizzare nella cache, chiamato "precache manifest", in base alle opzioni fornite.

Inoltre, accetta opzioni aggiuntive che configurano il comportamento del servizio di lavoro, ad esempio eventuali regole runtimeCaching da utilizzare.

In base al manifest precache e alla configurazione aggiuntiva, scrive sul disco un file del servizio worker pronto per l'uso 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 memorizzare nella cache, chiamato "precache manifest", 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

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 memorizzare nella cache, chiamato "precache manifest", in base alle opzioni fornite.

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 del servizio worker finale, con il manifest iniettato, viene scritto sul disco in swDest.

Questo metodo non compila né aggrega il file swSrc, ma si occupa solo di eseguire l'iniezione 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