Este guia se concentra nas mudanças interruptivas introduzidas na Workbox v4, com exemplos das mudanças que você precisa fazer ao fazer upgrade da Workbox v3.
Alterações importantes
workbox-precaching
A convenção de nomenclatura para entradas pré-armazenadas em cache foi atualizada. Agora, para entradas cujos URLs precisam de informações de revisão (ou seja, aquelas 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 a IndexedDB.
Os desenvolvedores que aproveitam o pré-armazenamento em cache pelo workbox.precaching.precacheAndRoute(), que é o caso de uso mais comum, não precisam fazer alterações 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. A partir de agora, os recursos pré-armazenados em cache continuarão sendo veiculados da mesma forma que antes.
Como usar as chaves de cache diretamente
Alguns desenvolvedores podem precisar acessar as entradas de pré-cache diretamente, fora do contexto de workbox.precaching.precacheAndRoute(). Por exemplo, é possível pré-armazenar em cache uma imagem que você acaba usando como uma resposta "substituta" quando uma imagem real não pode ser buscada na rede.
Se você usar recursos pré-armazenados em cache dessa forma, a partir da Workbox v4, será necessário realizar outra etapa para traduzir um URL original na chave de cache correspondente que pode ser usada para ler a entrada 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 pré-cache na Workbox v4 significam que os pré-caches mais antigos, criados por versões anteriores da Workbox, não são compatíveis. Por padrão, eles são mantidos como estão. Se você fizer upgrade da Workbox v3 para a v4, vai ter duas cópias de todos os recursos pré-armazenados.
Para evitar isso, adicione uma chamada para workbox.precaching.cleanupOutdatedCaches() a um worker de serviço diretamente ou defina 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 em convenções de nomenclatura de cache para encontrar precaches mais antigos e porque os desenvolvedores têm a opção de substituir essas convenções, erramos por segurança e não ativamos essa opção por padrão.
Incentivamos os desenvolvedores que tiverem problemas ao usar isso, como falsos positivos em relação à exclusão, a nos informar.
Capitalização de parâmetros
Dois parâmetros opcionais que podem ser transmitidos para workbox.precaching.precacheAndRoute() e workbox.precaching.addRoute() foram renomeados para padronizar nossa convenção de capitalização geral. ignoreUrlParametersMatching agora é ignoreURLParametersMatching e cleanUrls agora é cleanURLs.
workbox-strategies
Há duas maneiras mais ou menos equivalentes de criar uma instância de um gerenciador em workbox-strategies. O método de fábrica está sendo descontinuado para chamar explicitamente o 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({...});
Embora a sintaxe do método de fábrica continue funcionando na v4, o uso dela vai gerar um aviso. Recomendamos que os desenvolvedores migrem antes da remoção do suporte na versão v5.
workbox-background-sync
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 havia 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 reproduzidas (requestWillEnqueue, requestWillReplay, queueDidReplay). No entanto, a maioria dos desenvolvedores descobriu que, além da observação, eles queriam controlar como a fila era reproduzida, incluindo a capacidade de modificar, reordenar ou até mesmo cancelar solicitações individuais de forma dinâmica.
Na v4, esses callbacks foram removidos em favor de um único callback onSync, que é invocado sempre que uma tentativa de repetição é feita pelo navegador. 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 matriz listados acima para repetir a fila como 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 forma.
workbox-expiration
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.
workbox-broadcast-update
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.
workbox-core
Na Workbox v3, o nível de detalhamento dos níveis de registro podia ser controlado pelo método workbox.core.setLogLevel(), em que você transmitia um dos valores no tipo enumerado workbox.core.LOG_LEVELS. Também é possível ler o nível de registro atual usando workbox.core.logLevel.
Na Workbox v4, todas essas opções foram removidas, já que todas as ferramentas modernas para desenvolvedores agora vêm com recursos avançados de filtragem de registros. Consulte Como filtrar a saída do console nas Ferramentas para Desenvolvedores do Chrome.
workbox-sw
Dois métodos antes expostos diretamente no namespace workbox (que corresponde ao módulo workbox-sw) foram movidos para workbox.core. workbox.skipWaiting() passou a ser workbox.core.skipWaiting() e, da mesma forma, workbox.clientsClaim() passou a ser workbox.core.clientsClaim().
Configuração da ferramenta de build
O nome de algumas opções que podem ser transmitidas para workbox-cli, workbox-build ou workbox-webpack-plugin mudou. O uso de "Url" no nome de uma opção foi descontinuado em favor de "URL". Isso significa que os seguintes nomes de opções são preferidos:
dontCacheBustURLsMatchingignoreURLParametersMatchingmodifyURLPrefixtemplatedURLs
A variação "Url" desses nomes de opções ainda funciona na v4, mas resultará em uma mensagem de aviso. Recomendamos que os desenvolvedores façam a migração antes do lançamento da v5.
Nova funcionalidade
workbox-window
O novo módulo workbox-window simplifica o processo de registro do worker do serviço e a detecção de atualizações, além de fornecer um meio padrão de comunicação entre o código executado no worker do serviço e o código executado no contexto window do 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á-la quando apropriado. Saiba mais sobre o uso de workbox-window no guia do módulo.
Exemplo de migração
Um exemplo de migração real da Workbox v3 para a v4 pode ser encontrado neste pull request.
Receber ajuda
A maioria das migrações deve ser simples. Se você encontrar problemas não abordados neste guia, abra um problema no GitHub.