Les développeurs qui ont déjà utilisé sw-precache et/ou sw-toolbox peuvent passer facilement à la famille de bibliothèques Workbox. La mise à niveau vers Workbox offrira une expérience de service worker moderne et extensible, avec un débogage amélioré et une ergonomie développeur.
Modifications de la configuration existante
Si vous utilisez sw-precache configuré avec l'une des options suivantes, vous devez prendre en compte les modifications suivantes lors de la migration vers Workbox.
Options renommées
Le paramètre de configuration dynamicUrlToDependencies a été renommé templatedURLs.
Le paramètre de configuration staticFileGlobs a été renommé globPatterns.
Le paramètre de configuration runtimeCaching utilise un ensemble d'options mis à jour, correspondant aux noms utilisés dans les modules Workbox sous-jacents. Pour illustrer le changement de nom, cette configuration sw-precache:
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
équivaut à la configuration de la boîte de travail suivante:
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,
},
},
}],
Options obsolètes
Les itinéraires comportant des caractères génériques de style Express ne sont plus acceptés. Si vous utilisiez des routes génériques de type Express dans la configuration runtimeCaching ou directement dans sw-toolbox, migrez vers une route d'expression régulière équivalente lorsque vous utilisez Workbox.
Migrations sw-precache
De la CLI sw-precache à workbox-cli
Pour les développeurs qui utilisent l'interface de ligne de commande sw-precache, en exécutant la commande manuellement ou dans le cadre d'un processus de compilation basé sur npm scripts, le module workbox-cli est le moyen le plus simple d'effectuer la migration. L'installation de workbox-cli vous permettra d'accéder à un binaire appelé workbox.
Bien que la CLI sw-precache prend en charge la configuration via des indicateurs de ligne de commande ou un fichier de configuration, la CLI workbox exige que toutes les options de configuration soient fournies dans un fichier de configuration, à l'aide de CommonJS module.exports.
La CLI workbox accepte un certain nombre de modes différents. (Utilisez workbox --help pour les afficher toutes.) Toutefois, le mode qui correspond le mieux à la fonctionnalité de sw-precache est generateSW. Donc, un appel à
$ sw-precache --config='sw-precache-config.js'
peut être exprimée sous la forme
$ workbox generateSW workbox-config.js
Du module de nœud sw-precache au module de nœud workbox-build
Les développeurs qui utilisent l'API node pour sw-precache, soit dans le cadre d'un workflow gulp/Grunt, soit simplement dans un script de compilation node personnalisé, peuvent migrer en basculant vers le module workbox-build node.
La fonction generateSW() du module workbox-build correspond le mieux à la fonction write() du module sw-precache. L'une des principales différences est que generateSW() renvoie toujours une promesse, tandis que l'ancienne fonction write() prenait en charge à la fois une interface basée sur une promesse et une interface de rappel.
Utilisation de gulp, le cas échéant
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
peut être remplacé par
const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
return workboxBuild.generateSW({
// Config options.
});
});
Du plug-in sw-precache-webpack-plugin vers le plug-in Workbox webpack
Les développeurs qui utilisent sw-precache-webpack-plugin dans le cadre de leur processus de compilation webpack peuvent migrer vers la classe GenerateSW dans le module workbox-webpack-plugin.
workbox-webpack-plugin s'intègre directement au processus de création de Webpack et "connaît" tous les éléments générés par une compilation donnée. Cela signifie que, dans de nombreux cas d'utilisation, vous pouvez compter sur le comportement par défaut de workbox-webpack-plugin sans configuration supplémentaire et obtenir un service worker équivalent à celui fourni par sw-precache-webpack-plugin.
const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new SWPrecacheWebpackPlugin({
dontCacheBustUrlsMatching: /\.\w{8}\./,
filename: 'service-worker.js',
}),
],
};
peut être remplacé par
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
Migrations de sw- Toolkit
Passez du kit SWW fabriqué à la main à workbox-sw
Si vous utilisiez sw-toolbox directement (plutôt que implicitement via l'option runtimeCaching de sw-precache), la migration vers Workbox nécessite des ajustements manuels pour obtenir le comportement équivalent. Pour en savoir plus, consultez la documentation sur les modules workbox-routing et workbox-strategies.
Voici quelques extraits de code qui vous aideront à effectuer la migration. Ce code 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;
équivaut au code de la boîte de travail:
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());
Obtenir de l'aide
Nous estimons que la plupart des migrations vers Workbox devraient être simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, veuillez nous signaler un problème sur GitHub.