Os desenvolvedores que já usaram sw-precache e/ou sw-toolbox têm um caminho de upgrade simples para a família de bibliotecas do Workbox. O upgrade para o Workbox vai proporcionar uma experiência de service worker moderna e extensível, com depuração aprimorada e ergonomia para o desenvolvedor.
Modificações na configuração atual
Se você estiver usando o sw-precache configurado com uma das opções abaixo, considere as mudanças abaixo ao migrar para o Workbox.
Opções renomeadas
O parâmetro de configuração dynamicUrlToDependencies foi renomeado como templatedURLs.
O parâmetro de configuração staticFileGlobs foi renomeado como globPatterns.
O parâmetro de configuração runtimeCaching usa um conjunto atualizado de opções que correspondem aos nomes usados nos módulos do Workbox. Para ilustrar o que foi renomeado, esta configuração sw-precache:
runtimeCaching: [{
urlPattern: /api/,
handler: 'fastest',
options: {
cache: {
name: 'my-api-cache',
maxEntries: 5,
maxAgeSeconds: 60,
},
},
}],
equivale a esta configuração do 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,
},
},
}],
Opções descontinuadas
Rotas de caracteres curinga no estilo expresso não são mais compatíveis. Se você estava usando rotas de caractere curinga no estilo Express na configuração runtimeCaching ou diretamente no sw-toolbox, migre para uma rota de expressão regular equivalente ao usar o Workbox.
Migrações sw-precache
Da CLI sw-precache para o workbox-cli
Para os desenvolvedores que usam a interface de linha de comando sw-precache, executando o comando manualmente ou como parte de um processo de build baseado em npm scripts, o módulo workbox-cli é a maneira mais fácil de migrar. A instalação do workbox-cli permite que você acesse um binário chamado workbox.
Embora a CLI sw-precache tenha suporte à configuração por flags de linha de comando ou um arquivo de configuração, a CLI workbox exige que todas as opções de configuração sejam fornecidas em um arquivo de configuração, usando o CommonJS module.exports.
A CLI workbox é compatível com vários modos diferentes. Use workbox --help para conferir todos eles. Mas o modo que mais se aproxima da funcionalidade de sw-precache é generateSW. Então, uma chamada para
$ sw-precache --config='sw-precache-config.js'
pode ser expressa como
$ workbox generateSW workbox-config.js
Do módulo de nó sw-precache para o módulo de nó workbox-build
Os desenvolvedores que usam a API node para sw-precache, como parte de um fluxo de trabalho gulp/Grunt ou apenas dentro de um script de build node personalizado, podem migrar alternando para o módulo node workbox-build.
A função generateSW() do módulo workbox-build corresponde melhor à função write() do módulo sw-precache. Uma diferença importante é que generateSW() sempre retorna uma promessa, enquanto a função write() antiga aceitava um callback e uma interface baseada em promessas.
Uso de gulp nas linhas de
const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
return swPrecache.write('service-worker.js', {
// Config options.
});
});
pode ser alterado para
const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
return workboxBuild.generateSW({
// Config options.
});
});
Do sw-precache-webpack-plugin para o plug-in webpack da caixa de trabalho
Os desenvolvedores que usam o sw-precache-webpack-plugin como parte do processo de build do webpack podem migrar para a classe GenerateSW no módulo workbox-webpack-plugin.
O workbox-webpack-plugin integra-se diretamente ao processo de build do webpack e "sabe" de todos os recursos gerados por uma determinada compilação. Isso significa que, para muitos casos de uso, é possível confiar no comportamento padrão do workbox-webpack-plugin sem configuração extra e ter um service worker equivalente ao que o sw-precache-webpack-plugin fornece.
const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new SWPrecacheWebpackPlugin({
dontCacheBustUrlsMatching: /\.\w{8}\./,
filename: 'service-worker.js',
}),
],
};
pode ser alterado para
const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
// ...
plugins: [
new GenerateSW({
// Config options, if needed.
}),
],
};
Migrações sw-".
Migrar do sw-toolkit criado manualmente para o workbox-sw
Se você estava usando o sw-toolbox diretamente, em vez de usar implicitamente com a opção runtimeCaching do sw-precache, a migração para o Workbox exigirá alguns ajustes manuais para conseguir o comportamento equivalente. Se quiser mais contexto, leia a documentação dos módulos workbox-routing e workbox-strategies.
Confira alguns snippets de código para ajudar a orientar a migração. Este código 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 este código do 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());
Receber ajuda
Acreditamos que a maioria das migrações para o Workbox serão simples. Se você tiver problemas não abordados neste guia, abra um problema no GitHub.