Gli sviluppatori che hanno utilizzato in precedenza sw-precache e/o sw-toolbox hanno un percorso di upgrade semplice alla famiglia di librerie Workbox. L'upgrade a Workbox fornirà un'esperienza moderna ed estensibile con il servizio worker, con un debug e un'ergonomia dello sviluppatore migliorati.
Modifiche alla configurazione esistente
Se utilizzi sw-precache configurato con una delle seguenti opzioni, dovrai prendere in considerazione le modifiche seguenti durante la migrazione a Workbox.
Opzioni rinominate
Il parametro di configurazione dynamicUrlToDependencies è stato rinominato templatedURLs.
Il parametro di configurazione staticFileGlobs è stato rinominato globPatterns.
Il parametro di configurazione runtimeCaching accetta un insieme aggiornato di opzioni, corrispondenti ai nomi utilizzati nei moduli Workbox sottostanti. Per illustrare cosa è stato rinominato, questa configurazione sw-precache:
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
è equivalente a questa configurazione di Workbox:
runtimeCaching: [{
urlPattern: /api/,
// 'fastest' is now 'StaleWhileRevalidate'
handler: 'StaleWhileRevalidate',
options: {
// options.cache.name is now options.cacheName
cacheName: 'my-api-cache',
// options.cache is now options.expiration
expiration: {
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
Opzioni ritirate
I percorsi con caratteri jolly in stile Express non sono più supportati. Se utilizzavi percorsi con caratteri jolly in stile Express nella configurazione di runtimeCaching o direttamente in sw-toolbox, esegui la migrazione a un percorso con espressione regolare equivalente quando utilizzi Workbox.
Migrazioni sw-precache
Dall'interfaccia a riga di comando sw-precache a workbox-cli
Gli sviluppatori che utilizzano l'interfaccia a riga di comando sw-precache, eseguono il comando manualmente o nell'ambito di un processo di compilazione basato su npm scripts, troveranno il modulo workbox-cli il modo più semplice per eseguire la migrazione. L'installazione di workbox-cli ti consentirà di accedere a un file binario denominato workbox.
Sebbene l'interfaccia a riga di comando sw-precache supporti la configurazione tramite flag a riga di comando o un file di configurazione, l'interfaccia a riga di comando workbox richiede che tutte le opzioni di configurazione vengano fornite in un file di configurazione utilizzando CommonJS module.exports.
La CLI workbox supporta una serie di modalità diverse. (Utilizza workbox --help per visualizzarli tutti.) Tuttavia, la modalità più simile alla funzionalità di sw-precache è generateSW. Quindi una chiamata a
$ sw-precache --config='sw-precache-config.js'
può essere espresso come
$ workbox generateSW workbox-config.js
Dal modulo del nodo sw-precache al modulo del nodo workbox-build
Gli sviluppatori che utilizzano l'API node per sw-precache, nell'ambito di un flusso di lavoro gulp/Grunt o semplicemente all'interno di uno script di build node personalizzato, possono eseguire la migrazione passando al modulo workbox-build node.
La funzione generateSW() del modulo workbox-build corrisponde maggiormente alla funzione write() del modulo sw-precache. Una differenza fondamentale è che generateSW() restituisce sempre una promessa, mentre la vecchia funzione write() supportava sia un callback sia un'interfaccia basata su promesse.
Utilizzo di gulp in linea con
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
può essere modificato in
const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
return workboxBuild.generateSW({
// Config options.
});
});
Dal plug-in sw-precache-webpack al plug-in webpack di Workbox
Gli sviluppatori che utilizzano sw-precache-webpack-plugin come parte del processo di creazione del proprio webpack possono eseguire la migrazione passando alla classe GenerateSW all'interno del modulo workbox-webpack-plugin.
workbox-webpack-plugin si integra direttamente con il processo di compilazione di webpack e "conosce" tutte le risorse generate da una determinata compilazione. Ciò significa che, per molti casi d'uso, puoi fare affidamento sul comportamento predefinito di workbox-webpack-plugin senza configurazione aggiuntiva e ottenere un service worker equivalente a quello fornito da sw-precache-webpack-plugin.
const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new SWPrecacheWebpackPlugin({
dontCacheBustUrlsMatching: /\.\w{8}\./,
filename: 'service-worker.js',
}),
],
};
può essere modificato in
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
Migrazioni di sw-toolbox
Eseguire la migrazione da sw-toolbox creato manualmente a workbox-sw
Se utilizzavi sw-toolbox direttamente (anziché implicitamente tramite l'opzione runtimeCaching di sw-precache), la migrazione a Workbox richiede alcuni aggiustamenti manuali per ottenere il comportamento equivalente. Per maggiore contesto, leggi la documentazione relativa ai moduli workbox-routing e workbox-strategies.
Ecco alcuni snippet di codice per facilitare la migrazione. Questo codice di sw-toolbox:
importScripts('path/to/sw-toolbox.js');
// Set up a route that matches HTTP 'GET' requests.
toolbox.router.get(
// Match any URL that contains 'ytimg.com', regardless of
// where in the URL that match occurs.
/\.ytimg\.com\//,
// Apply a cache-first strategy to anything that matches.
toolbox.cacheFirst,
{
// Configure a custom cache name and expiration policy.
cache: {
name: 'youtube-thumbnails',
maxEntries: 10,
maxAgeSeconds: 30,
},
}
);
// Set a default network-first strategy to use when
// there is no explicit matching route:
toolbox.router.default = toolbox.networkFirst;
è equivalente a questo codice Workbox:
importScripts('path/to/workbox-sw.js');
workbox.routing.registerRoute(
// Match any URL that contains 'ytimg.com'.
// Unlike in sw-toolbox, in Workbox, a RegExp that matches
// a cross-origin URL needs to include the initial 'https://'
// as part of the match.
new RegExp('^https://.*.ytimg.com'),
// Apply a cache-first strategy to anything that matches.
new workbox.strategies.CacheFirst({
// Configuration options are passed in to the strategy.
cacheName: 'youtube-thumbnails',
plugins: [
new workbox.expiration.ExpirationPlugin({
maxEntries: 10,
maxAgeSeconds: 30,
}),
// In Workbox, you must explicitly opt-in to caching
// responses with a status of 0 when using the
// cache-first strategy.
new workbox.cacheableResponse.CacheableResponsePlugin({
statuses: [0, 200],
}),
],
})
);
// Set a default network-first strategy to use when
// there is no explicit matching route:
workbox.routing.setDefaultHandler(new workbox.strategies.NetworkFirst());
Richiesta di aiuto
Prevediamo che la maggior parte delle migrazioni a Workbox sarà semplice. Se riscontri problemi non trattati in questa guida, comunicacelo aprendo un problema su GitHub.