Entwickler, die in der Vergangenheit sw-precache und/oder sw-toolbox verwendet haben, können ganz einfach auf die Workbox-Bibliotheken upgraden. Ein Upgrade auf Workbox bietet eine moderne, erweiterbare Umgebung mit verbessertem Debugging und verbesserter Ergonomie für Entwickler.
Änderungen an Ihrer bestehenden Konfiguration
Wenn Sie sw-precache verwenden, für das eine der folgenden Optionen konfiguriert ist, 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.
Für den Konfigurationsparameter runtimeCaching wird ein aktualisierter Satz von Optionen verwendet, die den Namen entsprechen, die in den zugrunde liegenden Workbox-Modulen verwendet werden. Um zu veranschaulichen, was umbenannt wurde, zeigt diese sw-precache-Konfiguration:
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
Platzhalterrouten im Express-Stil werden nicht mehr unterstützt. Wenn Sie Platzhalterrouten im Express-Stil entweder in der runtimeCaching-Konfiguration oder direkt in sw-toolbox verwendet haben, migrieren Sie bei Verwendung von Workbox zu einer entsprechenden Route mit regulären Ausdrücken.
sw-precache-Migrationen
Von der Befehlszeile „sw-precache“ zu „workbox-cli“
Für Entwickler, die die sw-precache-Befehlszeile verwenden und den Befehl entweder manuell oder im Rahmen eines npm scripts-basierten Build-Prozesses ausführen, ist die Verwendung des workbox-cli-Moduls die einfachste Möglichkeit für die Migration. Wenn du workbox-cli installierst, erhältst du Zugriff auf ein Binärprogramm namens workbox.
Die sw-precache-Befehlszeile unterstützt die Konfiguration über Befehlszeilen-Flags oder eine Konfigurationsdatei. Für die workbox-Befehlszeile müssen alle Konfigurationsoptionen in einer Konfigurationsdatei mit CommonJS module.exports angegeben werden.
Die workbox-Befehlszeile unterstützt eine Reihe verschiedener Modi. (Verwenden Sie workbox --help, um alle zu sehen.) Der Modus, der der Funktionalität von sw-precache am ehesten entspricht, ist jedoch generateSW. Ein Aufruf an die
$ sw-precache --config='sw-precache-config.js'
können folgendermaßen ausgedrückt werden:
$ workbox generateSW workbox-config.js
Vom Knotenmodul „sw-precache“ zum Knotenmodul „workbox-build“
Entwickler, die die node API für sw-precache entweder als Teil eines gulp/Grunt-Workflows oder nur innerhalb eines benutzerdefinierten node-Build-Skripts verwenden, können zum workbox-build node-Modul wechseln.
Die Funktion generateSW() des Moduls workbox-build entspricht am ehesten der Funktion write() des Moduls sw-precache. Ein wesentlicher Unterschied besteht darin, dass generateSW() immer ein Promise-Objekt zurückgibt, während die alte write()-Funktion sowohl einen Callback als auch eine Promise-basierte Schnittstelle unterstützt.
gulp-Nutzung im Vergleich zu
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
kann geändert werden zu
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 im workbox-webpack-plugin-Modul zur GenerateSW-Klasse wechseln.
workbox-webpack-plugin lässt sich direkt in den Webpack-Build-Prozess einbinden und „weiß“ alle Assets, die mit einer bestimmten Kompilierung generiert wurden. Das bedeutet, dass Sie sich für viele Anwendungsfälle auf das Standardverhalten von workbox-webpack-plugin ohne zusätzliche Konfiguration verlassen und einen Service Worker abrufen können, 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 geändert werden zu
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
sw-toolbox-Migrationen
Von handgearbeiteten Sw-Toolbox zu Workbox-sw migrieren
Wenn Sie sw-toolbox direkt (anstatt implizit über die runtimeCaching-Option von sw-precache) verwendet haben, sind bei der Migration zu Workbox einige manuelle Anpassungen erforderlich, 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 die Migration erleichtern. 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 diesem 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());
Unterstützung erhalten
Wir gehen davon aus, dass die meisten Migrationen zu Workbox unkompliziert sein werden. Wenn Probleme auftreten, die nicht in diesem Leitfaden beschrieben sind, erheben Sie ein Problem in GitHub.