Eseguire la migrazione da Workbox v5 a v6

Questa guida è incentrata sulle modifiche non compatibili introdotte nella versione 6 di Workbox, con esempi delle modifiche da apportare durante l'upgrade dalla versione 5 di Workbox.

Modifiche che provocano un errore

workbox-core

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

D'ora in poi, utilizza invece self.skipWaiting() poiché skipWaiting() verrà probabilmente rimosso in Workbox v7.

workbox-precaching

  • I documenti HTML multiorigine per gli URL che corrispondono a un reindirizzamento HTTP non possono più essere utilizzati per soddisfare una richiesta di navigazione con workbox-precaching. In genere questo scenario è insolito.
  • Il parametro di query dell'URL fbclid viene ora ignorato da workbox-precaching quando viene cercata una risposta precompilata per una determinata richiesta.
  • Il costruttore PrecacheController ora accetta come parametro un oggetto con proprietà specifiche anziché una stringa. Questo oggetto supporta le seguenti proprietà: cacheName (che ha lo stesso scopo della stringa passata al costruttore nella versione v5), plugins (sostituisce il metodo addPlugins() dalla versione v5) e fallbackToNetwork (sostituisce l'opzione simile passata a createHandler() e "createGestoriBoundToURL() nella versione v5).
  • I metodi install() e activate() di PrecacheController ora utilizzano esattamente un parametro, che dovrebbe essere impostato rispettivamente su 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 da registrare.
  • Il metodo precacheAndRoute() è stato rimosso da PrecacheController. Esiste ancora come metodo helper statico esportato dal modulo workbox-precaching. È stato rimosso perché al suo posto è possibile utilizzare PrecacheRoute.
  • Il metodo createMatchCalback() è stato rimosso da PrecacheController. Al suo posto puoi utilizzare il nuovo PrecacheRoute.
  • Il metodo createHandler() è stato rimosso da PrecacheController. Per gestire le richieste è invece possibile utilizzare la proprietà strategy dell'oggetto PrecacheController.
  • L'esportazione statica di createHandler() è già stata rimossa dal modulo workbox-precaching. Al loro posto, gli sviluppatori dovrebbero creare un'istanza PrecacheController e usare la relativa proprietà strategy.
  • Il percorso registrato con precacheAndRoute() è ora un percorso "reale" che utilizza la classe Router di workbox-routing. Ciò potrebbe comportare un ordine di valutazione diverso delle route se incrocia le chiamate a registerRoute() e precacheAndRoute().

workbox-routing

Il metodo setDefaultHandler() ora accetta un secondo parametro facoltativo corrispondente al metodo HTTP a cui si applica, con un valore predefinito di 'GET'.

  • Se utilizzi setDefaultHandler() e tutte le tue richieste sono GET, non è necessaria alcuna modifica.
  • Se hai richieste diverse da GET (POST, PUT e così via), setDefaultHandler() non comporterà più la corrispondenza di 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. Questo non si applica a workbox-webpack-plugin, che supporta mode nel plug-in InjectManifest.

Gli strumenti di compilazione richiedono Node.js 10 o versioni successive

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

Nuovi miglioramenti

workbox-strategies

La versione 6 di Workbox introduce un nuovo modo per gli sviluppatori di terze parti di definire le proprie strategie Workbox. In questo modo, gli sviluppatori di terze parti hanno la possibilità di estendere Workbox in modo da soddisfare completamente le loro esigenze.

Nuova classe di base Strategy

Nella versione 6, tutte le classi di strategia di Workbox devono estendere la nuova classe base Strategy. Tutte le strategie predefinite sono state riscritte per supportare questa funzionalità.

La classe di base Strategy è responsabile di due aspetti principali:

  • Richiamo dei callback del ciclo di vita del plug-in comuni a tutti gli handler delle strategie (ad es. quando iniziano, rispondono e terminano).
  • È in corso la creazione di un'istanza "handler", che può gestire lo stato per ogni singola richiesta gestita da una strategia.

Nuova classe "handler"

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

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

Questo tipo di classe consentirebbe inoltre agli sviluppatori di aggiungere i propri callback personalizzati del ciclo di vita che potrebbero essere specifici per le loro strategie e che "funzionano e basta" con l'interfaccia del plug-in esistente.

Nuovo stato del ciclo di vita del plug-in

In Workbox 5, i plug-in sono stateless. Ciò significa che se una richiesta di /index.html attiva sia i callback requestWillFetch che cachedResponseWillBeUsed, questi due callback non hanno modo di comunicare tra loro o di sapere che sono stati attivati dalla stessa richiesta.

Nella versione 6, a tutti i callback dei plug-in verrà passato anche un nuovo oggetto state. Questo oggetto stato sarà univoco per questo particolare oggetto plug-in e per questa particolare chiamata alla strategia (ovvero la chiamata a handle()). In questo modo, gli sviluppatori possono scrivere plug-in in cui un callback può fare qualcosa in modo condizionale in base a ciò che ha fatto un altro callback nello stesso plug-in (ad es. calcolare il delta di tempo tra l'esecuzione di requestWillFetch e fetchDidSucceed o fetchDidFail).

Callback del ciclo di vita dei nuovi 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: viene chiamato prima dell'avvio dell'esecuzione della logica dell'handler. Questo callback può essere utilizzato per impostare lo stato iniziale del gestore (ad es. registrare l'ora di inizio).
  • handlerWillRespond: richiamato 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 eventuali dettagli della risposta finale, ad esempio dopo le modifiche apportate da altri plug-in.
  • handlerDidComplete: viene chiamato dopo che tutte le promesse di durata estesa aggiunte all'evento dall'invocazione di questa strategia sono state risolte. Questo callback può essere utilizzato per generare report su tutti i dati che devono attendere il completamento del gestore per essere calcolati (ad es. stato di hit della cache, latenza della cache, latenza della rete).
  • handlerDidError: chiamato se il gestore non è stato in grado di fornire una risposta valida da nessuna origine. Questo callback può essere utilizzato per fornire contenuti "di riserva" come alternativa a un errore di rete.

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

Tipi TypeScript più precisi per i gestori

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

finestra-box di lavoro

Nuovo metodo messageSkipWaiting()

Al modulo workbox-window è stato aggiunto un nuovo metodo, messageSkipWaiting(), per semplificare la procedura di attivazione del service worker"in attesa". Questa funzionalità offre alcuni miglioramenti:

  • Chiama postMessage() con il corpo del messaggio standard de facto, {type: 'SKIP_WAITING'}, che un worker di servizio 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 degli 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 si preoccupano della distinzione possono comunque rilevarla, mentre quelli che non ne hanno bisogno possono ignorare la proprietà.

Ricetta più chiara "Offri agli utenti una ricarica della pagina"

Grazie a entrambe le modifiche precedenti, la ricetta "Offri un ricaricamento della pagina per gli utenti" può essere semplificata:

MULTI_LINE_CODE_PLACEHOLDER_0

workbox-routing

Un nuovo parametro booleano, sameOrigin, viene passato alla funzione matchCallback utilizzata in workbox-routing. Il valore è impostato su true se la richiesta riguarda un URL della stessa origine, altrimenti è false.

In questo modo, vengono semplificati 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.

workbox-precaching

Utilizza workbox-strategies

workbox-precaching è stato riscritto in modo da utilizzare workbox-strategies come base. Ciò non dovrebbe comportare modifiche incompatibili e dovrebbe portare a una maggiore coerenza a lungo termine nel modo in cui i due moduli accedono alla rete e alla cache.

Il pre-caching ora elabora le voci una alla volta, non collettivamente

workbox-precaching è stato aggiornato in modo che venga richiesta e memorizzata nella cache una sola voce del manifest di precache alla volta, anziché tentare di richiederle e memorizzarle tutte contemporaneamente (lasciando al browser il compito di capire come gestire la limitazione).

Ciò dovrebbe ridurre la probabilità che si verifichino errori di net::ERR_INSUFFICIENT_RESOURCES durante la pre-memorizzazione nella cache e dovrebbe anche ridurre il conflitto di larghezza di banda tra la pre-memorizzazione nella cache 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 di ciclo di vita handlerDidError aggiunto nella versione 6.

In questo modo è facile specificare un URL precompilato come "alternativa" per una determinata strategia quando altrimenti non sarebbe disponibile una risposta. Il plug-in creerà correttamente la chiave cache corretta per l'URL pre-memorizzato nella cache, inclusi eventuali parametri di revisione necessari.

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

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback nella memorizzazione nella cache in fase di runtime

Se utilizzi generateSW per creare un servizio worker per te anziché scriverlo manualmente, puoi utilizzare la nuova opzione di configurazione precacheFallback in runtimeCaching per ottenere lo stesso risultato:

{
  // ... 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',
      },
    },
  }],
}

Risorse di assistenza

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