Este guia tem como foco as alterações interruptivas introduzidas no Workbox v4, com exemplos das alterações necessárias ao fazer upgrade do Workbox v3.
Alterações importantes
pré-armazenamento em cache da caixa de trabalho
A convenção de nomenclatura para entradas armazenadas previamente em cache foi atualizada. Agora, para entradas com URLs que precisam de informações de revisão (ou seja, as entradas que contêm um campo revision no manifesto de pré-cache), essas informações de controle de versão serão armazenadas como parte da chave de cache, em um parâmetro de consulta de URL __WB_REVISION__ especial anexado ao URL original. Antes, essas informações eram armazenadas separadamente das chaves de cache usando o IndexedDB.
Os desenvolvedores que aproveitam o pré-armazenamento em cache via workbox.precaching.precacheAndRoute(), que é o caso de uso mais comum, não precisam fazer mudanças na configuração do service worker. Após o upgrade para o Workbox v4, os recursos em cache dos usuários serão migrados automaticamente para o novo formato de chave de cache. Daqui em diante, os recursos pré-armazenados em cache vão continuar sendo disponibilizados da mesma maneira que antes.
Como usar as chaves de cache diretamente
Alguns desenvolvedores talvez precisem acessar entradas de pré-cache diretamente, fora do contexto de workbox.precaching.precacheAndRoute(). Por exemplo, você pode colocar em cache uma imagem que acaba usando como resposta "substituta" quando uma imagem real não pode ser buscada na rede.
A partir do Workbox v4, você vai precisar de uma etapa adicional para converter um URL original na chave de cache correspondente, que pode ser usada para ler a entrada armazenada em cache. Para fazer isso, chame workbox.precaching.getCacheKeyForURL(originURL).
Por exemplo, se você souber que 'fallback.png' está pré-armazenado em cache:
const imageFallbackCacheKey =
workbox.precaching.getCacheKeyForURL('fallback.png');
workbox.routing.setCatchHandler(({event}) => {
switch (event.request.destination) {
case 'image':
return caches.match(imageFallbackCacheKey);
break;
// ...other fallback logic goes here...
}
});
Como limpar dados antigos pré-armazenados em cache
As mudanças feitas no armazenamento em cache no Workbox v4 significam que os pré-caches mais antigos, criados por versões anteriores do Workbox, não são compatíveis. Por padrão, eles são deixados como estão, e se você atualizar do Workbox v3 para o Workbox v4, terá duas cópias de todos os seus recursos armazenados previamente em cache.
Para evitar isso, você pode adicionar chamadas para workbox.precaching.cleanupOutdatedCaches() diretamente a um service worker ou definir a nova opção cleanupOutdatedCaches: true se estiver usando uma ferramenta de build no modo GenerateSW. Como a lógica de limpeza de cache opera de acordo com convenções de nomenclatura de cache para encontrar pré-caches mais antigos e os desenvolvedores têm a opção de substituir essas convenções, optamos pela segurança e não ativamos esse recurso por padrão.
Recomendamos que os desenvolvedores que encontrarem problemas ao usar esse recurso, como falsos positivos na exclusão, informem nossa equipe.
Capitalização de parâmetro
Dois parâmetros opcionais que podem ser passados para workbox.precaching.precacheAndRoute() e workbox.precaching.addRoute() foram renomeados para padronizar nossa convenção geral de uso de letras maiúsculas. ignoreUrlParametersMatching agora é ignoreURLParametersMatching e cleanUrls agora é cleanURLs.
estratégias de caixa de trabalho
Há duas maneiras aproximadamente equivalentes de criar uma instância de um gerenciador em workbox-strategies. Estamos descontinuando o método de fábrica em favor da chamada explícita do construtor da estratégia.
// This factory method syntax has been deprecated:
const networkFirstStrategy = workbox.strategies.networkFirst({...});
// Instead, use the constructor directly:
// (Note that the class name is Uppercase.)
const networkFirstStrategy = new workbox.strategies.NetworkFirst({...});
A sintaxe do método de fábrica continuará funcionando na v4, mas o uso dela registrará um aviso. Recomendamos que os desenvolvedores migrem antes de remover o suporte na próxima versão v5.
caixa de trabalho-sincronização em segundo plano
A classe workbox.backgroundSync.Queue foi reescrita para oferecer aos desenvolvedores mais flexibilidade e controle sobre como as solicitações são adicionadas à fila e reproduzidas.
Na v3, a classe Queue tinha uma única maneira de adicionar solicitações à fila (o método addRequest()), mas não tinha como modificar a fila ou remover solicitações.
Na v4, o método addRequests() foi removido e os seguintes métodos semelhantes a matrizes foram adicionados:
pushRequest()popRequest()shiftRequest()unshiftRequest()
Na v3, a classe Queue também aceitava vários callbacks que permitiam observar quando as solicitações estavam sendo repetidas (requestWillEnqueue, requestWillReplay, queueDidReplay), mas a maioria dos desenvolvedores descobriu que, além da observação, eles queriam controle sobre como a fila era repetida, incluindo a capacidade de modificar, reordenar ou até cancelar solicitações individuais dinamicamente.
Na v4, esses callbacks foram substituídos por um único callback onSync, que é invocado sempre que o navegador faz uma tentativa de repetição. Por padrão, o callback onSync invoca replayRequests(), mas se você precisar de mais controle sobre o processo de repetição, use os métodos semelhantes a matrizes listados acima para reproduzir a fila da maneira que quiser.
Confira um exemplo de lógica de repetição personalizada:
const queue = new workbox.backgroundSync.Queue('my-queue-name', {
onSync: async ({queue}) => {
let entry;
while ((entry = await this.shiftRequest())) {
try {
await fetch(entry.request);
} catch (error) {
console.error('Replay failed for request', entry.request, error);
await this.unshiftRequest(entry);
return;
}
}
console.log('Replay complete!');
},
});
Da mesma forma, a classe workbox.backgroundSync.Plugin aceita os mesmos argumentos que a classe Queue (já que cria uma instância Queue internamente), então ela mudou da mesma maneira.
caixa-de-trabalho-validade
O pacote npm foi renomeado como workbox-expiration, correspondendo à convenção de nomenclatura usada para outros módulos. Esse pacote é funcionalmente equivalente ao pacote workbox-cache-expiration mais antigo, que foi descontinuado.
caixa de trabalho-transmissão-atualização
O pacote npm foi renomeado como workbox-broadcast-update, correspondendo à convenção de nomenclatura usada para outros módulos. Esse pacote é funcionalmente equivalente ao pacote workbox-broadcast-cache-update mais antigo, que foi descontinuado.
caixa de trabalho-núcleo
No Workbox v3, o nível de detalhes dos níveis de registro pode ser controlado pelo método workbox.core.setLogLevel(), que transmite um dos valores da enumeração workbox.core.LOG_LEVELS. Também é possível ler o nível de registro atual via workbox.core.logLevel.
No Workbox v4, todas essas opções foram removidas, já que todas as ferramentas para desenvolvedores modernas vêm com recursos avançados de filtragem de registros. Consulte Como filtrar a saída do console para o Chrome Dev Tools.
caixa de trabalho-sw
Dois métodos que estavam expostos diretamente no namespace workbox (que corresponde ao módulo workbox-sw) foram movidos para workbox.core. workbox.skipWaiting() agora é workbox.core.skipWaiting(), e workbox.clientsClaim() agora é workbox.core.clientsClaim().
Configuração da ferramenta de build
A nomenclatura de algumas opções que podem ser transmitidas para workbox-cli, workbox-build ou workbox-webpack-plugin mudou. Sempre que "Url" é usado em um nome de opção, o uso dele é suspenso e substituído por "URL". Isso significa que os seguintes nomes de opção são preferidos:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
A variação "Url" desses nomes de opções ainda funciona na v4, mas resultará em uma mensagem de aviso. Incentivamos os desenvolvedores a migrar antes da versão v5.
Nova funcionalidade
caixa de trabalho-janela
O novo módulo workbox-window simplifica o processo de registro do service worker e detecção de atualizações, além de fornecer um meio padrão de comunicação entre o código em execução no service worker e o código em execução no contexto window do seu app da Web.
Embora o uso de workbox-window seja opcional, esperamos que ele seja útil para os desenvolvedores e considere migrar parte da lógica escrita à mão para usá-lo quando apropriado. Saiba mais sobre como usar workbox-window no guia do módulo.
Exemplo de migração
Um exemplo de migração do mundo real do Workbox v3 para o v4 pode ser encontrado nesta solicitação de envio.
Receber ajuda
Acreditamos que a maioria das migrações serão simples. Se você tiver problemas não abordados neste guia, abra um problema no GitHub.