Entwickler, die zuvor sw-precache und/oder sw-toolbox verwendet haben, können ganz einfach auf die Workbox-Bibliotheken umstellen. Das Upgrade auf Workbox bietet eine moderne, erweiterbare Service-Worker-Erfahrung mit verbesserter Fehlerbehebung und verbesserter Ergonomie für Entwickler.
Änderungen an der vorhandenen Konfiguration
Wenn Sie sw-precache mit einer der folgenden Optionen konfiguriert haben, müssen Sie bei der Migration zu Workbox die folgenden Änderungen berücksichtigen.
Umbenannte Optionen
Der Konfigurationsparameter dynamicUrlToDependencies wurde in templatedURLs umbenannt.
Der Konfigurationsparameter staticFileGlobs wurde in globPatterns umbenannt.
Der Konfigurationsparameter runtimeCaching akzeptiert eine aktualisierte Reihe von Optionen, die den Namen entsprechen, die in den zugrunde liegenden Workbox-Modulen verwendet werden. Zur Veranschaulichung der Umbenennung:sw-precache
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
entspricht dieser Workbox-Konfiguration:
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,
},
},
}],
Eingestellte Optionen
Express-ähnliche Routen mit Platzhaltern werden nicht mehr unterstützt. Wenn Sie Express-Platzhalterrouten entweder in der runtimeCaching-Konfiguration oder direkt in sw-toolbox verwendet haben, sollten Sie bei der Verwendung von Workbox zu einer entsprechenden regulären Ausdrucksroute migrieren.
sw-precache-Migrationen
Von der sw-precache-CLI zur workbox-cli
Für Entwickler, die die sw-precache-Befehlszeile verwenden, entweder manuell oder als Teil eines npm scripts-basierten Build-Prozesses, ist die Migration mit dem workbox-cli-Modul am einfachsten. Wenn Sie workbox-cli installieren, erhalten Sie Zugriff auf eine Binärdatei namens workbox.
Während die sw-precache-Befehlszeile die Konfiguration über Befehlszeilen-Flags oder eine Konfigurationsdatei unterstützt, müssen für die workbox-Befehlszeile alle Konfigurationsoptionen in einer Konfigurationsdatei unter Verwendung von CommonJS module.exports angegeben werden.
Die workbox-Befehlszeile unterstützt verschiedene Modi. (Verwenden Sie workbox --help, um alle anzuzeigen.) Der Modus, der der Funktionalität von sw-precache am ehesten entspricht, ist jedoch generateSW. Ein Call-to-Action
$ sw-precache --config='sw-precache-config.js'
kann ausgedrückt werden als
$ workbox generateSW workbox-config.js
Vom Node-Modul „sw-precache“ zum Node-Modul „workbox-build“
Entwickler, die die node API für sw-precache verwenden, entweder als Teil eines gulp/Grunt-Workflows oder nur in einem benutzerdefinierten node-Build-Script, können migrieren, indem sie zum workbox-build node-Modul wechseln.
Die Funktion generateSW() des workbox-build-Moduls entspricht am ehesten der Funktion write() des sw-precache-Moduls. Ein wichtiger Unterschied besteht darin, dass generateSW() immer ein Promise zurückgibt, während die alte write()-Funktion sowohl einen Callback als auch eine Promise-basierte Schnittstelle unterstützte.
Nutzung von gulp entsprechend
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
kann in
const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
return workboxBuild.generateSW({
// Config options.
});
});
Vom sw-precache-webpack-plugin zum Workbox-Webpack-Plug-in
Entwickler, die sw-precache-webpack-plugin im Rahmen ihres webpack-Build-Prozesses verwenden, können migrieren, indem sie im workbox-webpack-plugin-Modul zur Klasse GenerateSW wechseln.
workbox-webpack-plugin wird direkt in den Webpack-Build-Prozess eingebunden und kennt alle Assets, die durch eine bestimmte Kompilierung generiert wurden. Das bedeutet, dass Sie sich in vielen Anwendungsfällen ohne zusätzliche Konfiguration auf das Standardverhalten von workbox-webpack-plugin verlassen können und einen Service Worker erhalten, der dem von sw-precache-webpack-plugin entspricht.
const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new SWPrecacheWebpackPlugin({
dontCacheBustUrlsMatching: /\.\w{8}\./,
filename: 'service-worker.js',
}),
],
};
kann in
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
sw-toolbox-Migrationen
Von einer benutzerdefinierten SW-Toolbox zu workbox-sw migrieren
Wenn Sie sw-toolbox direkt verwendet haben (und nicht implizit über die Option runtimeCaching von sw-precache), erfordert die Migration zu Workbox einige manuelle Anpassungen, um das entsprechende Verhalten zu erzielen. Weitere Informationen finden Sie in der Dokumentation zu den Modulen workbox-routing und workbox-strategies.
Im Folgenden finden Sie einige Code-Snippets, die Ihnen bei der Migration helfen. Dieser sw-toolbox-Code:
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;
entspricht dem folgenden Workbox-Code:
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());
Hilfe erhalten
Wir gehen davon aus, dass die meisten Migrationen zu Workbox unkompliziert sein werden. Wenn Probleme auftreten, die in diesem Leitfaden nicht behandelt werden, erstelle bitte einen Issue auf GitHub.