Eseguire la migrazione da Workbox v5 a v6

Questa guida si concentra sulle modifiche che provocano errori introdotte in Workbox v6, con esempi delle modifiche necessarie per eseguire l'upgrade da Workbox v5.

Modifiche che provocano un errore

core box di lavoro

Il metodo skipWaiting() in workbox-core non aggiungerà più un gestore install ed equivale alla semplice chiamata di self.skipWaiting().

D'ora in poi, usa invece self.skipWaiting() perché è probabile che skipWaiting() venga rimosso in Workbox v7.

pre-memorizzazione nella cache della casella di lavoro

  • Non è più possibile utilizzare i documenti HTML multiorigine per gli URL che corrispondono a un reindirizzamento HTTP per soddisfare una richiesta di navigazione con workbox-precaching. Questo scenario è generalmente raro.
  • Il parametro di query dell'URL fbclid ora viene ignorato da workbox-precaching quando si cerca una risposta pre-memorizzata nella cache per una determinata richiesta.
  • Il costruttore PrecacheController ora accetta un oggetto con proprietà specifiche come parametro, anziché una stringa. Questo oggetto supporta le seguenti proprietà: cacheName (che serve lo stesso scopo della stringa passata al costruttore nella v5), plugins (sostituisce il metodo addPlugins() dalla v5) e fallbackToNetwork (che sostituisce l'opzione simile passata a createHandler() e "createHandlerBoundToURL() nella v5).
  • I metodi install() e activate() di PrecacheController ora utilizzano esattamente un parametro, che deve essere impostato rispettivamente su un InstallEvent o ActivateEvent corrispondente.
  • Il metodo addRoute() è stato rimosso da PrecacheController. Al suo posto, la nuova classe PrecacheRoute può essere utilizzata per creare un percorso che puoi quindi registrare.
  • Il metodo precacheAndRoute() è stato rimosso da PrecacheController. Esiste ancora come metodo helper statico esportato dal modulo workbox-precaching. È stato rimosso perché è possibile utilizzare PrecacheRoute.
  • Il metodo createMatchCalback() è stato rimosso da PrecacheController. Puoi usare il nuovo PrecacheRoute.
  • Il metodo createHandler() è stato rimosso da PrecacheController. La proprietà strategy dell'oggetto PrecacheController può essere utilizzata per gestire le richieste.
  • L'esportazione statica createHandler() è già stata rimossa dal modulo workbox-precaching. Al suo posto, gli sviluppatori dovrebbero creare un'istanza PrecacheController e utilizzare la relativa proprietà strategy.
  • Il percorso registrato con precacheAndRoute() ora è un percorso "reale" che utilizza la classe Router di workbox-routing. Se interfoli le chiamate a registerRoute() e precacheAndRoute(), questo potrebbe comportare un ordine di valutazione diverso dei tuoi percorsi.

routing-casella di lavoro

Il metodo setDefaultHandler() ora richiede un secondo parametro facoltativo corrispondente al metodo HTTP a cui si applica, il cui valore predefinito è 'GET'.

  • Se utilizzi setDefaultHandler() e tutte le tue richieste sono GET, non devi apportare modifiche.
  • Se hai richieste diverse da GET (POST, PUT e così via), setDefaultHandler() non farà più corrispondere queste richieste.

Configurazione build

L'opzione mode per le modalità getManifest e injectManifest in workbox-build e workbox-cli non era destinata a essere supportata ed è stata rimossa. Non si applica a workbox-webpack-plugin, che supporta mode nel suo plug-in InjectManifest.

Gli strumenti di creazione richiedono Node.js v10 o versioni successive

Le versioni di Node.js precedenti alla v10 non sono più supportate per workbox-webpack-plugin, workbox-build o workbox-cli. Se esegui una versione di Node.js precedente alla v8, aggiorna il runtime a una versione supportata.

Nuovi miglioramenti

strategie-workbox

Workbox v6 introduce un nuovo modo per gli sviluppatori di terze parti per definire le proprie strategie Workbox. Questo assicura che gli sviluppatori di terze parti abbiano la possibilità di estendere Workbox in modi che soddisfano pienamente le loro esigenze.

Classe di base Nuova strategia

Nella versione 6, tutte le classi di strategia Workbox devono estendere la nuova classe base Strategy. A questo scopo, sono state riscritte tutte le strategie integrate.

La classe base Strategy è responsabile di due aspetti principali:

  • Richiamo di callback del ciclo di vita dei plug-in comuni a tutti i gestori di strategie (ad es. quando iniziano, rispondono e terminano).
  • Creazione di un'istanza "handler", in grado di gestire lo stato di ogni singola richiesta gestita da una strategia.

Nuova classe "handler"

In precedenza avevamo moduli interni chiamati fetchWrapper e cacheWrapper che (come suggerisce il nome) aggregano le varie API di recupero e cache con hook nel loro ciclo di vita. Si tratta del meccanismo che attualmente consente il funzionamento dei plug-in, ma non è esposto agli sviluppatori.

La nuova classe "handler", StrategyHandler, mostrerà questi metodi in modo che le strategie personalizzate possano chiamare fetch() o cacheMatch() e avere tutti i plug-in aggiunti all'istanza della strategia che vengono richiamati automaticamente.

Questa classe consentirebbe inoltre agli sviluppatori di aggiungere callback personalizzati del ciclo di vita, che potrebbero essere specifici per le loro strategie, e "funzionano" semplicemente con l'interfaccia dei plug-in esistente.

Nuovo stato del ciclo di vita dei plug-in

In Workbox v5, i plug-in sono stateless. Ciò significa che se una richiesta per /index.html attiva entrambi i callback requestWillFetch e cachedResponseWillBeUsed, questi due callback non possono comunicare tra loro né sapere che sono stati attivati dalla stessa richiesta.

Nella versione 6, a tutti i callback dei plug-in viene passato anche un nuovo oggetto state. Questo oggetto di stato sarà univoco per questo oggetto plug-in specifico e per questa chiamata di strategia specifica (ovvero la chiamata a handle()). Ciò consente agli sviluppatori di scrivere plug-in in cui un callback può eseguire un'azione in base alle azioni eseguite da un altro callback nello stesso plug-in (ad esempio calcolando il delta temporale tra l'esecuzione di requestWillFetch e fetchDidSucceed o fetchDidFail).

Nuovi callback del ciclo di vita dei plug-in

Sono stati aggiunti nuovi callback del ciclo di vita dei plug-in per consentire agli sviluppatori di sfruttare appieno lo stato del ciclo di vita dei plug-in:

  • handlerWillStart: richiamato prima dell'esecuzione di qualsiasi logica di gestore. Questo callback può essere utilizzato per impostare lo stato iniziale di gestore (ad es. registrare l'ora di inizio).
  • handlerWillRespond: chiamato prima che il metodo handle() delle strategie restituisca una risposta. Questo callback può essere utilizzato per modificare la risposta prima di restituirla a un gestore di route o a un'altra logica personalizzata.
  • handlerDidRespond: richiamato dopo che il metodo handle() della strategia restituisce una risposta. Questo callback può essere utilizzato per registrare i dettagli finali della risposta, ad esempio dopo le modifiche apportate da altri plug-in.
  • handlerDidComplete: richiamato dopo che tutte le promesse di durata estesa aggiunte all'evento dal richiamo di questa strategia sono state risolte. Questo callback può essere utilizzato per generare report sui dati che devono attendere il completamento del gestore per poterli calcolare (ad esempio, stato di successo della cache, latenza della cache, latenza di rete).
  • handlerDidError: chiamato se il gestore non è stato in grado di fornire una risposta valida da qualsiasi origine. Questo callback può essere utilizzato per fornire contenuti "di riserva" in alternativa a un errore di rete.

Gli sviluppatori che implementano le proprie strategie personalizzate non devono preoccuparsi di richiamare autonomamente questi callback, il tutto gestito da una nuova classe base Strategy.

Tipi TypeScript più precisi per i gestori

Le definizioni TypeScript per i vari metodi di callback sono state normalizzate. Questo dovrebbe portare a un'esperienza migliore per gli sviluppatori che usano TypeScript e scrivono il proprio codice per implementare o chiamare i gestori.

finestra-casella di lavoro

Nuovo metodo messageSkipPending()

È stato aggiunto un nuovo metodo, messageSkipWaiting(), al modulo workbox-window per semplificare il processo di attivazione del service worker"in attesa". Questa opzione offre alcuni miglioramenti:

  • Chiama postMessage() con il corpo del messaggio standard de facto, {type: 'SKIP_WAITING'}, che un service worker generato da Workbox controlla per attivare skipWaiting().
  • Sceglie il service worker "in attesa" corretto su cui pubblicare questo messaggio, anche se non si tratta dello stesso service worker con cui è stato registrato workbox-window.

Rimozione di eventi "esterni" a favore di una proprietà isExternal

Tutti gli eventi "external" in workbox-window sono stati rimossi al posto degli eventi "normali" con una proprietà isExternal impostata su true. In questo modo, gli sviluppatori che tengono alla distinzione possono comunque rilevarla, mentre quelli che non hanno bisogno di saperli possono ignorare la proprietà.

Ricetta più pulita "Offri il ricaricamento di una pagina agli utenti"

Grazie a entrambe le modifiche riportate sopra, la formula "Offri il ricaricamento di una pagina agli utenti" può essere semplificata:

MULTI_LINE_CODE_PLACEHOLDER_0

routing-casella di lavoro

Un nuovo parametro booleano, sameOrigin, viene trasmesso alla funzione matchCallback utilizzata in workbox-routing. È impostato su true se la richiesta riguarda un URL della stessa origine e su false negli altri casi.

Questo semplifica alcuni boilerplate comuni:

MULTI_LINE_CODE_PLACEHOLDER_1

matchOptions in workbox-expiration

Ora puoi impostare matchOptions in workbox-expiration, che verrà poi trasmesso come CacheQueryOptions alla chiamata cache.delete() sottostante. La maggior parte degli sviluppatori non dovrà farlo.

pre-memorizzazione nella cache della casella di lavoro

Utilizza strategie-workbox

workbox-precaching è stato riscritto in modo da utilizzare workbox-strategies come base. Questo non dovrebbe comportare modifiche che provocano errori e dovrebbe portare a una migliore coerenza a lungo termine nel modo in cui i due moduli accedono alla rete e alla cache.

La pre-memorizzazione nella cache ora elabora le voci una alla volta, non in blocco

workbox-precaching è stato aggiornato in modo che venga richiesta e memorizzata nella cache una sola voce alla volta nel file manifest di pre-cache, invece di cercare di richiederle e memorizzarle tutte nella cache contemporaneamente (lasciando il file al browser per capire come limitarle).

Ciò dovrebbe ridurre la probabilità che si verifichino errori di net::ERR_INSUFFICIENT_RESOURCES durante la pre-memorizzazione e dovrebbe anche ridurre la contesa della larghezza di banda tra la pre-memoria e le richieste simultanee effettuate dall'app web.

PrecacheFallbackPlugin consente un fallback offline più semplice

workbox-precaching ora include un PrecacheFallbackPlugin, che implementa il nuovo metodo del ciclo di vita handlerDidError aggiunto nella v6.

In questo modo è più semplice specificare un URL prememorizzato nella cache come "riserva" per una determinata strategia quando una risposta non sarebbe disponibile in altro modo. Il plug-in si occuperà di creare correttamente la chiave cache corretta per l'URL prememorizzato nella cache, incluso qualsiasi parametro di revisione necessario.

Di seguito è riportato un esempio di utilizzo per rispondere con un /offline.html prememorizzato nella cache quando la strategia NetworkOnly non è in grado di generare una risposta per una richiesta di navigazione. In altre parole, viene visualizzata una pagina HTML offline personalizzata:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback nella memorizzazione nella cache di runtime

Se utilizzi generateSW per creare un service worker per te invece di scriverlo manualmente, puoi utilizzare la nuova opzione di configurazione precacheFallback in runtimeCaching per eseguire la stessa operazione:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

Richiedere assistenza

Prevediamo che la maggior parte delle migrazioni sarà semplice. Se riscontri problemi non trattati in questa guida, comunicacelo aprendo un problema su GitHub.