Este guia se concentra nas alterações interruptivas introduzidas no Workbox v6, com exemplos das alterações que você precisa fazer ao fazer upgrade do Workbox v5.
Alterações importantes
núcleo da caixa de trabalho
O método skipWaiting() em workbox-core não adicionará mais um gerenciador install e é equivalente a apenas chamar self.skipWaiting()
A partir de agora, use self.skipWaiting(), já que o skipWaiting() provavelmente será removido no Workbox v7.
pré-armazenamento em cache da caixa de trabalho
- Documentos HTML de origem cruzada para URLs que correspondem a um redirecionamento HTTP não podem mais ser usados para atender a uma solicitação de navegação com
workbox-precaching. Esse cenário costuma ser incomum. - O parâmetro de consulta do URL
fbclidagora é ignorado porworkbox-precachingao procurar uma resposta pré-armazenada em cache para uma determinada solicitação - O construtor
PrecacheControlleragora aceita um objeto com propriedades específicas como parâmetro, em vez de uma string. Esse objeto é compatível com as seguintes propriedades:cacheName(com a mesma finalidade que a string transmitida para o construtor na v5),plugins(substituindo o métodoaddPlugins()da v5) efallbackToNetwork(substituindo a opção semelhante que foi transmitida paracreateHandler()e `createHandlerBoundToURL() na v5). - Os métodos
install()eactivate()dePrecacheControlleragora usam exatamente um parâmetro, que precisa ser definido como umInstallEventouActivateEventcorrespondente, respectivamente - O método
addRoute()foi removido dePrecacheControllerNo lugar dela, a nova classePrecacheRoutepode ser usada para criar uma rota que pode ser registrada. - O método
precacheAndRoute()foi removido dePrecacheControllerEle ainda existe como um método auxiliar estático exportado pelo móduloworkbox-precaching. Ele foi removido porquePrecacheRoutepode ser usado no lugar dele. - O método
createMatchCalback()foi removido dePrecacheControllerO novoPrecacheRoutepode ser usado nesse caso - O método
createHandler()foi removido dePrecacheControllerA propriedadestrategydo objetoPrecacheControllerpode ser usada para processar solicitações. - A exportação estática
createHandler()já foi removida do móduloworkbox-precaching. No lugar dela, os desenvolvedores precisam criar uma instância doPrecacheControllere usar a propriedadestrategy. - A rota registrada com
precacheAndRoute()agora é uma rota "real" que usa a classeRouterdoworkbox-routinginternamente. Isso pode levar a uma ordem de avaliação diferente das suas rotas se você intercalar as chamadas pararegisterRoute()eprecacheAndRoute().
roteamento da caixa de trabalho
O método setDefaultHandler() agora usa um segundo parâmetro opcional correspondente ao método HTTP a que se aplica, com o padrão 'GET'.
- Se você usar
setDefaultHandler()e todas as suas solicitações foremGET, nenhuma mudança precisará ser feita. - Se você tiver solicitações que não sejam
GET(POST,PUTetc.),setDefaultHandler()não fará mais com que essas solicitações sejam correspondentes.
Configuração do Cloud Build
A opção mode para os modos getManifest e injectManifest em workbox-build e workbox-cli não deveria ter suporte e foi removida Isso não se aplica a workbox-webpack-plugin, que oferece suporte a mode no plug-in InjectManifest.
As ferramentas de build exigem o Node.js v10 ou mais recente
As versões do Node.js anteriores à v10 não são mais compatíveis com workbox-webpack-plugin, workbox-build ou workbox-cli. Se você estiver executando uma versão do Node.js anterior à v8, atualize o ambiente de execução para uma versão compatível.
Novas melhorias
estratégias de caixa de trabalho
O Workbox v6 apresenta uma nova maneira para desenvolvedores terceirizados definirem as próprias estratégias do Workbox. Isso garante que os desenvolvedores terceirizados possam estender o Workbox de maneiras que atendam totalmente às necessidades deles.
Nova classe base "Strategy"
Na v6, todas as classes de estratégia do Workbox precisam estender a nova classe de base Strategy. Todas as estratégias integradas foram reescritas para dar suporte a esse recurso.
A classe de base Strategy é responsável por duas coisas principais:
- Invocar callbacks do ciclo de vida do plug-in comuns a todos os gerenciadores de estratégia (por exemplo, quando eles iniciam, respondem e terminam).
- Criar uma instância de "gerenciador" que possa gerenciar o estado de cada solicitação individual processada por uma estratégia.
Nova classe "Handler"
Anteriormente, tínhamos módulos internos chamados fetchWrapper e cacheWrapper que (como o nome indica) uniam as várias APIs de busca e armazenamento em cache com hooks no ciclo de vida. Atualmente, esse é o mecanismo que permite que os plug-ins funcionem, mas que não está exposto aos desenvolvedores.
A nova classe "gerenciador", StrategyHandler, vai expor esses métodos para que as estratégias personalizadas possam chamar fetch() ou cacheMatch() e ter plug-ins adicionados à instância da estratégia automaticamente invocados.
Essa classe também possibilita que os desenvolvedores adicionem seus próprios callbacks de ciclo de vida personalizados que podem ser específicos para suas estratégias, e eles "simplesmente funcionam" com a interface de plug-in existente.
Novo estado do ciclo de vida do plug-in
No Workbox v5, os plug-ins não têm estado. Isso significa que, se uma solicitação para /index.html acionar os callbacks requestWillFetch e cachedResponseWillBeUsed, eles não vão ter como se comunicar entre si nem saber que foram acionados pela mesma solicitação.
Na v6, todos os callbacks do plug-in também vão receber um novo objeto state. Esse objeto de estado será exclusivo para esse objeto de plug-in específico e esta invocação de estratégia específica (ou seja, a chamada para handle()). Isso permite que os desenvolvedores programem plug-ins em que um callback possa fazer algo condicionalmente com base no que outro callback no mesmo plug-in fez (por exemplo, calcular o delta de tempo entre a execução de requestWillFetch e fetchDidSucceed ou fetchDidFail).
Novos callbacks do ciclo de vida do plug-in
Novos callbacks do ciclo de vida do plug-in foram adicionados para permitir que os desenvolvedores aproveitem ao máximo o estado do ciclo de vida do plug-in:
handlerWillStart: chamado antes de qualquer lógica do gerenciador começar a ser executada. Esse callback pode ser usado para definir o estado inicial do gerenciador (por exemplo, registrar o horário de início).handlerWillRespond: chamado antes de o métodohandle()das estratégias retornar uma resposta. Esse callback pode ser usado para modificar essa resposta antes de retorná-la a um gerenciador de rotas ou a outra lógica personalizada.handlerDidRespond: chamado depois que o métodohandle()da estratégia retorna uma resposta. Esse callback pode ser usado para registrar os detalhes da resposta final, por exemplo, depois de alterações feitas por outros plug-ins.handlerDidComplete: chamado depois que todas as promessas de ciclo de vida adicionadas ao evento na invocação dessa estratégia forem resolvidas. Esse retorno de chamada pode ser usado para relatar qualquer dado que precise aguardar até que o gerenciador seja concluído para calcular (por exemplo, status de ocorrência em cache, latência de cache, latência de rede).handlerDidError: chamado se o gerenciador não conseguir fornecer uma resposta válida de qualquer origem. Esse callback pode ser usado para fornecer conteúdo "substituto" como uma alternativa a um erro de rede.
Os desenvolvedores que implementam as próprias estratégias personalizadas não precisam se preocupar em invocar esses próprios callbacks. Tudo isso é processado por uma nova classe de base Strategy.
Tipos do TypeScript mais precisos para gerenciadores
As definições do TypeScript para vários métodos de callback foram normalizadas Isso vai melhorar a experiência dos desenvolvedores que usam o TypeScript e escrevem o próprio código para implementar ou chamar gerenciadores.
janela-da-caixa de trabalho
Novo método messageSkipWait()
Um novo método, messageSkipWaiting(), foi adicionado ao módulo workbox-window para simplificar o processo de solicitação do service worker"em espera" para ativar. Isso oferece algumas melhorias:
- Ele chama
postMessage()com o corpo da mensagem padrão real,{type: 'SKIP_WAITING'}, que um service worker gerado pelo Workbox verifica para acionarskipWaiting(). - Ele escolhe o service worker "aguardando" correto para postar essa mensagem, mesmo que não seja o mesmo service worker com que
workbox-windowfoi registrado.
Remoção de eventos "externos" em favor de uma propriedade isExternal.
Todos os eventos "external" em workbox-window foram removidos no lugar dos eventos "normais" com uma propriedade isExternal definida como true. Isso permite que os desenvolvedores que se importam com a distinção ainda a detectem, e aqueles que não precisam saber podem ignorar a propriedade.
Limpeza do roteiro "Oferecer uma atualização de página para os usuários"
Graças às duas alterações acima, a receita "Oferecer uma atualização de página para os usuários" pode ser simplificada:
MULTI_LINE_CODE_PLACEHOLDER_0
roteamento da caixa de trabalho
Um novo parâmetro booleano, sameOrigin, é transmitido para a função matchCallback usada em workbox-routing. Ele será definido como true se a solicitação for para um URL da mesma origem. Caso contrário, será falso.
Isso simplifica alguns códigos boilerplate comuns:
MULTI_LINE_CODE_PLACEHOLDER_1
matchOptions em workbox-expiration
Agora você pode definir matchOptions em workbox-expiration, que vão ser transmitidos como CacheQueryOptions para a chamada cache.delete(). A maioria dos desenvolvedores não precisa fazer isso.
pré-armazenamento em cache da caixa de trabalho
Usa estratégias de caixa de trabalho
workbox-precaching foi reescrito para usar workbox-strategies como base. Isso não deve resultar em alterações interruptivas e melhorar a consistência a longo prazo na forma como os dois módulos acessam a rede e o cache.
O pré-armazenamento em cache agora processa as entradas uma por uma, não em massa.
A workbox-precaching foi atualizada para que apenas uma entrada no manifesto de pré-cache seja solicitada e armazenada em cache por vez, em vez de tentar solicitar e armazenar todas elas em cache de uma vez (deixando-o para o navegador para descobrir como limitar).
Isso deve reduzir a probabilidade de erros net::ERR_INSUFFICIENT_RESOURCES durante o pré-armazenamento em cache, além da contenção de largura de banda entre o pré-armazenamento em cache e as solicitações simultâneas feitas pelo app da Web.
O Precache{0/}Plugin possibilita um substituto off-line mais fácil.
workbox-precaching agora inclui um PrecacheFallbackPlugin, que implementa o novo método de ciclo de vida handlerDidError adicionado na v6
Isso facilita a especificação de um URL pré-armazenado em cache como um "substituto" para uma determinada estratégia quando uma resposta não estaria disponível. O plug-in vai criar corretamente a chave de cache correta para o URL pré-armazenado em cache, incluindo todos os parâmetros de revisão necessários.
Veja um exemplo de como usá-lo para responder com um /offline.html pré-armazenado em cache quando a estratégia NetworkOnly não consegue gerar uma resposta para uma solicitação de navegação. Em outras palavras, ela mostra uma página HTML off-line personalizada:
MULTI_LINE_CODE_PLACEHOLDER_2
precacheFallback no armazenamento em cache no ambiente de execução
Se você estiver usando generateSW para criar um service worker para você, em vez de programar o service worker manualmente, será possível usar a nova opção de configuração precacheFallback no runtimeCaching para conseguir o mesmo resultado:
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
Como buscar ajuda
A maioria das migrações é simples. Se você tiver problemas não abordados neste guia, abra um problema no GitHub.