O foco deste guia são as alterações interruptivas introduzidas no Workbox v3, com exemplos das mudanças que você precisa fazer ao fazer upgrade de uma configuração do Workbox v2.
Se você estiver usando a combinação legada sw-precache
/sw-toolbox
e quiser fazer a transição para o Workbox pela primeira vez, este guia de migração vai ajudar.
Plano de fundo da v3
A versão v3 do Workbox representa uma refatoração significativa da base de código existente. As metas gerais são:
- Minimize o tamanho da caixa de trabalho. A quantidade de códigos do ambiente de execução do service worker que é transferida por download e executado foi reduzida. Em vez de permitir que todos participem de um pacote monolítico, somente o código para os recursos específicos que você está usando será importado no ambiente de execução.
- O Workbox tem uma CDN. Oferecemos uma hospedagem de CDN totalmente compatível e baseada no Google Cloud Storage como opção canônica para acessar as bibliotecas de ambiente de execução do Workbox, facilitando a instalação e a execução dele.
- Melhor depuração e registros. A experiência de depuração e geração de registros foi bastante aprimorada. Os registros de depuração são ativados por padrão sempre que o Workbox é usado de uma origem
localhost
e todos os registros e declarações são removidos dos builds de produção. - Plug-in webpack aprimorado. O
workbox-webpack-plugin
se integra melhor ao processo de build do webpack, permitindo um caso de uso sem configuração quando você quer pré-armazenar em cache todos os recursos no pipeline de build.
Alcançar essas metas e limpar alguns aspectos da interface anterior que pareciam estranhos ou geravam antipadrões exigiu a introdução de uma série de alterações interruptivas na versão v3.
Alterações importantes
Configuração do Cloud Build
As mudanças abaixo afetam o comportamento de todas as nossas ferramentas de build (workbox-build
, workbox-cli
, workbox-webpack-plugin
), que compartilham o mesmo conjunto de opções de configuração.
- O nome do gerenciador
'fastest'
era válido e tratado como um alias para'staleWhileRevalidate'
ao configurarruntimeCaching
. Ele não é mais válido, e os desenvolvedores precisam passar a usar'staleWhileRevalidate'
diretamente. - Vários nomes de propriedades
runtimeCaching.options
foram atualizados e há uma validação de parâmetro adicional em vigor, que vai causar a falha do build se uma configuração inválida for usada. Consulte a documentação deruntimeCaching
para ver uma lista das opções compatíveis no momento.
workbox-background-sync
- O parâmetro de configuração
maxRetentionTime
agora é interpretado como um número de minutos, em vez de um número de milissegundos. - Agora há uma string obrigatória, representando o nome da fila, que deve ser passado como o primeiro parâmetro ao construir o plug-in ou a classe autônoma. Ele foi transmitido anteriormente como uma propriedade das opções. Consulte a documentação da plataforma atualizada da API.
workbox-broadcast-cache-update
- Agora há uma string obrigatória, que representa o nome do canal, que precisa ser transmitida como o primeiro parâmetro ao construir o plug-in ou a classe autônoma.
Por exemplo, na v2, você inicializaria a classe Plugin da seguinte maneira:
new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
channelName: 'cache-updates',
headersToCheck: ['etag'],
});
O uso equivalente na v3 é:
new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});
Consulte a documentação da plataforma atualizada da API.
workbox-build
- Por padrão, a correspondência de padrões
glob
agora é realizada com as opçõesfollow: true
(que virão depois dos links simbólicos) estrict: true
(que é menos tolerante a erros "incomuns"). É possível desativar ambos e retornar ao comportamento anterior definindoglobFollow: false
e/ouglobStrict: false
na configuração do build. - Todas as funções em
workbox-build
retornam uma propriedade extra,warnings
, nas respostas retornadas. Alguns cenários que eram tratados como erros fatais na v2 agora são permitidos, mas informados porwarnings
, que é uma matriz de strings.
Na v2, você pode chamar generateSW
da seguinte maneira:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
.catch((error) => console.error(`Something went wrong: ${error}`));
Embora você possa usar o mesmo código na v3, é recomendável verificar se há warnings
e registrá-los:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size, warnings}) => {
for (const warning of warnings) {
console.warn(warning);
}
console.log(`Precached ${count} files, totalling ${size} bytes.`);
})
.catch((error) => console.error(`Something went wrong: ${error}`));
- Os desenvolvedores que criaram as próprias funções
ManifestTransform
personalizadas na v2 precisam retornar a matriz do manifesto em um objeto. Ou seja, em vez dereturn manifestArray;
, usereturn {manifest: manifestArray};
.mIsso permite que seu plug-in inclua uma propriedadewarnings
opcional, que precisa ser uma matriz de strings contendo informações de aviso não fatais.
Se você estivesse criando um ManifestTransform
personalizado na v2, o código seria assim:
const cdnTransform = manifestEntries => {
return manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
};
tem um equivalente na v3 de:
const cdnTransform = manifestEntries => {
const manifest = manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
return {manifest, warnings: []};
};
- A função
getFileManifestEntries()
foi renomeada comogetManifest()
, e a promessa retornada agora inclui informações adicionais sobre os URLs que estão pré-armazenados em cache.
Insira o código abaixo na v2:
const manifestEntries = await workboxBuild.getFileManifestEntries({...});
pode ser reescrito na v3 como:
const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});
// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
- A função
generateFileManifest()
foi removida. Incentivamos os desenvolvedores a chamargetManifest()
e usar a resposta dele para gravar dados no disco no formato apropriado.
workbox-cache-expiration
- A API do plug-in permanece a mesma, que é o modo que a maioria dos desenvolvedores acabará usando. No entanto, há mudanças significativas na API que afetam os desenvolvedores que a usam como uma classe independente. Consulte a documentação da plataforma atualizada da API.
workbox-cli
Os desenvolvedores podem executar a CLI com a flag --help
para um conjunto completo de parâmetros com suporte.
- O suporte para o alias
workbox-cli
do script binário foi removido. O binário agora só pode ser acessado comoworkbox
. - Os comandos v2
generate:sw
einject:manifest
foram renomeados comogenerateSW
einjectManifest
na v3. - Na v2, o arquivo de configuração padrão (usado quando um não foi explicitamente fornecido) foi considerado
workbox-cli-config.js
no diretório atual. Na v3, éworkbox-config.js
.
Em conjunto, isso significa que na v2:
$ workbox inject:manifest
executaria o processo de compilação "inject manifest", usando uma configuração lida de workbox-cli-config.js
e na v3:
$ workbox injectManifest
fará o mesmo, mas lê a configuração de workbox-config.js
.
pré-armazenamento em cache da caixa de trabalho
- Anteriormente, o método
precache()
realizava as modificações de cache e configurou o roteamento para exibir entradas em cache. Agora,precache()
modifica apenas entradas de cache, e um novo método,addRoute()
, foi exposto para registrar uma rota para disponibilizar essas respostas armazenadas em cache. Os desenvolvedores que quiserem usar a funcionalidade dois em um anterior poderão começar a chamarprecacheAndRoute()
. - Várias opções que eram configuradas pelo construtor
WorkboxSW
agora são transmitidas como o parâmetrooptions
emworkbox.precaching.precacheAndRoute([...], options)
Os padrões dessas opções, quando não configurados, são listados nos documentos de referência. - Por padrão, os URLs sem extensão de arquivo são automaticamente verificados em busca de uma correspondência com uma entrada de cache que contém uma extensão
.html
. Por exemplo, se uma solicitação for feita para/path/to/index
(que não é pré-armazenada em cache) e houver uma entrada pré-armazenada em cache para/path/to/index.html
, essa entrada vai ser usada. Os desenvolvedores podem desativar esse novo comportamento definindo{cleanUrls: false}
ao transmitir opções paraworkbox.precaching.precacheAndRoute()
- O
workbox-broadcast-update
não será mais configurado automaticamente para anunciar atualizações de cache para recursos pré-armazenados em cache.
O código a seguir na v2:
const workboxSW = new self.WorkboxSW({
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);
tem um equivalente na v3 de:
workbox.precaching.addPlugins([
new workbox.broadcastUpdate.Plugin('precache-updates')
]);
workbox.precaching.precacheAndRoute([...], {
cleanUrls: false,
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
});
roteamento da caixa de trabalho
- Os desenvolvedores que já usavam o
workbox-routing
com o namespaceworkbox.router.*
de um objeto WorkboxSW precisam mudar para o novo namespace,workbox.routing.*
. - Agora os trajetos são avaliados em uma ordem "first-registered-wins". Esta é a ordem oposta de avaliação
Route
que foi usada na v2, em que o últimoRoute
registrado teria precedência. - A classe
ExpressRoute
e o suporte para caracteres curinga "estilo Express" foram removidos. Isso reduz consideravelmente o tamanho deworkbox-routing
. As strings usadas como o primeiro parâmetro paraworkbox.routing.registerRoute()
agora vão ser tratadas como correspondências exatas. Correspondências curinga ou parciais precisam ser tratadas porRegExp
s. Usar qualquerRegExp
que corresponda a parte ou a todo o URL da solicitação pode acionar uma rota. - O método auxiliar
addFetchListener()
da classeRouter
foi removido. Os desenvolvedores podem adicionar o próprio gerenciadorfetch
explicitamente ou usar a interface fornecida porworkbox.routing
, que cria implicitamente um gerenciadorfetch
para eles. - Os métodos
registerRoutes()
eunregisterRoutes()
foram removidos. As versões desses métodos que operam em uma únicaRoute
não foram modificadas, e os desenvolvedores que precisam registrar ou cancelar o registro de várias rotas de uma vez precisam fazer uma série de chamadas pararegisterRoute()
ouunregisterRoute()
.
O código a seguir na v2:
const workboxSW = new self.WorkboxSW();
workboxSW.router.registerRoute(
'/path/with/.*/wildcard/',
workboxSW.strategies.staleWhileRevalidate()
);
workboxSW.router.registerRoute(
new RegExp('^https://example.com/'),
workboxSW.strategies.networkFirst()
);
tem um equivalente na v3 de:
workbox.routing.registerRoute(
new RegExp('^https://example.com/'),
workbox.strategies.networkFirst()
);
workbox.routing.registerRoute(
new RegExp('^/path/with/.*/wildcard'),
workbox.strategies.staleWhileRevalidate()
);
estratégias de caixa de trabalho (anteriormente conhecidas como workbox-runtime-armazenamento em cache)
- O módulo
workbox-runtime-caching
agora é oficialmente conhecido comoworkbox-strategies
e foi publicado nonpm
com o novo nome. - Não é mais válido usar a expiração do cache em uma estratégia sem fornecer um nome de cache. Na v2, isso era possível:
workboxSW.strategies.staleWhileRevalidate({
cacheExpiration: {maxEntries: 50},
});
Isso levaria a entradas expiradas no cache padrão, o que é inesperado. Na v3, um nome de cache é obrigatório:
workboxSW.strategies.staleWhileRevalidate({
cacheName: 'my-cache',
plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
- O método
cacheWillMatch
do ciclo de vida foi renomeado comocachedResponseWillBeUsed
Essa mudança não será visível para os desenvolvedores, a menos que eles tenham criado os próprios plug-ins com reações aocacheWillMatch
. - A sintaxe para especificar plug-ins ao configurar uma estratégia foi alterada. Cada plug-in precisa estar explicitamente listado na propriedade
plugins
da configuração da estratégia.
O código a seguir na v2:
const workboxSW = new self.WorkboxSW();
const networkFirstStrategy = workboxSW.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
cacheExpiration: {
maxEntries: 50,
},
cacheableResponse: {
statuses: [0, 200],
},
});
tem um equivalente na v3 de:
const networkFirstStrategy = workbox.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
plugins: [
new workbox.expiration.Plugin({maxEntries: 50}),
new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
],
});
Saiba mais no guia Como usar plug-ins.
workbox-sw
- Internamente, o
workbox-sw
foi reescrito para ser uma interface de "carregador" leve, que requer uma configuração básica e é responsável por extrair os outros módulos necessários no momento da execução. Em vez de criar uma nova instância da classeWorkboxSW
, os desenvolvedores interagem com uma instância existente que é exposta automaticamente no namespace global.
Anteriormente na v2:
importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');
const workbox = new WorkboxSW({
skipWaiting: true,
clientsClaim: true,
// etc.
});
workbox.router.registerRoute(...);
Na v3, você só precisa importar o script workbox-sw.js
, e uma instância pronta para uso vai estar disponível automaticamente no namespace global como workbox
:
importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');
// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
skipWaiting
eclientsClaim
não são mais opções transmitidas para o construtorWorkboxSW
. Em vez disso, eles foram alterados para os métodosworkbox.clientsClaim()
eworkbox.skipWaiting()
.- A opção
handleFetch
, que anteriormente era compatível com o construtor v2, não tem mais suporte na v3. Os desenvolvedores que precisam de recursos semelhantes para testar o service worker sem que nenhum gerenciador de busca seja invocado podem usar a opção "Ignorar para a rede", disponível nas Ferramentas para desenvolvedores do Chrome.
plug-in-de-pacote-de-trabalho
O plug-in foi reescrito e, em muitos casos, pode ser usado no modo de "configuração zero". Consulte a documentação da plataforma atualizada da API.
- A API agora expõe duas classes,
GenerateSW
eInjectManifest
. Isso torna a alternância entre os modos explícita, em comparação com o comportamento da v2, em que o comportamento mudou com base na presença deswSrc
- Por padrão, os recursos no pipeline de compilação do webpack são pré-armazenados em cache e não é mais necessário configurar
globPatterns
. O único motivo para continuar usandoglobPatterns
é se você precisar armazenar em cache recursos não incluídos no build do webpack. Em geral, ao migrar para o plug-in v3, é preciso começar removendo toda a configuração anterior baseada emglob
e só adicionar de novo se você precisar.
Receber ajuda
Acreditamos que a maioria das migrações são simples. Se você tiver problemas não abordados neste guia, abra um problema no GitHub para nos informar.