Les développeurs qui ont déjà utilisé sw-precache et/ou sw-toolbox peuvent facilement passer à la famille de bibliothèques Workbox. La migration vers Workbox vous offrira une expérience de service worker moderne et extensible, avec une ergonomie améliorée pour le débogage et les développeurs.
Modifications apportées à votre configuration existante
Si vous utilisez sw-precache configuré avec l'une des options suivantes, vous devrez prendre en compte les modifications ci-dessous 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 ce qui a été renommé, voici une configuration sw-precache:
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
équivaut à cette configuration 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,
},
},
}],
Options obsolètes
Les routes génériques de style Express ne sont plus acceptées. Si vous utilisiez des routes génériques de style 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
Les développeurs qui utilisent l'interface de ligne de commande sw-precache, qu'ils exécutent la commande manuellement ou dans le cadre d'un npm scriptsprocessus de compilation, apprécieront le workbox-cli module de migration. L'installation de workbox-cli vous donne accès à un binaire appelé workbox.
Alors que la CLI sw-precache est compatible avec la configuration via des indicateurs de ligne de commande ou un fichier de configuration, la CLI workbox nécessite que toutes les options de configuration soient fournies dans un fichier de configuration, à l'aide de CommonJS module.exports.
La CLI workbox est compatible avec plusieurs modes différents. (Utilisez workbox --help pour les afficher tous.) Cependant, le mode qui correspond le mieux à la fonctionnalité de sw-precache est generateSW. Un appel à
$ sw-precache --config='sw-precache-config.js'
peut être exprimé comme suit :
$ 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 effectuer la migration en passant au module node workbox-build.
La fonction generateSW() du module workbox-build correspond le plus à la fonction write() du module sw-precache. Une différence clé est que generateSW() renvoie toujours une promesse, tandis que l'ancienne fonction write() acceptait à la fois un rappel et une interface basée sur une promesse.
Utilisation de gulp comme
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 au plug-in webpack Workbox
Les développeurs qui utilisent sw-precache-webpack-plugin dans le cadre de leur processus de compilation webpack peuvent migrer en passant à la classe GenerateSW dans le module workbox-webpack-plugin.
workbox-webpack-plugin s'intègre directement au processus de compilation webpack et "connaît" tous les éléments générés par une compilation donnée. Cela signifie que, pour de nombreux cas d'utilisation, vous pouvez vous fier au 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 sw-toolbox
Migrer de sw-toolbox manuel vers workbox-sw
Si vous utilisiez sw-toolbox directement (plutôt que de l'utiliser implicitement via l'option runtimeCaching de sw-precache), la migration vers Workbox nécessitera des ajustements manuels pour obtenir un comportement équivalent. Pour en savoir plus, consultez la documentation des 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;
est équivalent à ce code 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());
Obtenir de l'aide
Nous nous attendons à ce que la plupart des migrations vers Workbox soient simples. Si vous rencontrez des problèmes qui ne sont pas abordés dans ce guide, veuillez nous en informer en créant un problème sur GitHub.