Migrar do Workbox v5 para v6

Este guia se concentra nas mudanças interruptivas introduzidas na Workbox v6, com exemplos das mudanças que você precisa fazer ao fazer upgrade da Workbox v5.

Alterações importantes

workbox-core

O método skipWaiting() em workbox-core não vai mais adicionar um gerenciador install e será equivalente a chamar self.skipWaiting().

A partir de agora, use self.skipWaiting(), já que skipWaiting() provavelmente será removido na Workbox v7.

workbox-precaching

• Os 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 geralmente não é comum.
• O parâmetro de consulta do URL fbclid agora é ignorado por workbox-precaching ao procurar uma resposta pré-armazenada em cache para uma determinada solicitação.
• O construtor PrecacheController agora usa um objeto com propriedades específicas como parâmetro, em vez de uma string. Esse objeto oferece suporte às seguintes propriedades: cacheName (que tem a mesma finalidade da string transmitida ao construtor na v5), plugins (que substitui o método addPlugins() da v5) e fallbackToNetwork (que substitui a opção semelhante transmitida para createHandler() e "createHandlerBoundToURL()" na v5).
• Os métodos install() e activate() de PrecacheController agora usam exatamente um parâmetro, que precisa ser definido como InstallEvent ou ActivateEvent correspondente, respectivamente.
• O método addRoute() foi removido de PrecacheController. No lugar dela, a nova classe PrecacheRoute pode ser usada para criar uma rota que você pode registrar.
• O método precacheAndRoute() foi removido de PrecacheController. Ele ainda existe como um método auxiliar estático exportado pelo módulo workbox-precaching. Ele foi removido porque PrecacheRoute pode ser usado.
• O método createMatchCalback() foi removido de PrecacheController. O novo PrecacheRoute pode ser usado.
• O método createHandler() foi removido de PrecacheController. A propriedade strategy do objeto PrecacheController pode ser usada para processar solicitações.
• A exportação estática createHandler() já foi removida do módulo workbox-precaching. Em vez disso, os desenvolvedores precisam criar uma instância PrecacheController e usar a propriedade strategy dela.
• A rota registrada com precacheAndRoute() agora é uma rota "real" que usa a classe Router de workbox-routing. Isso pode levar a uma ordem de avaliação diferente das rotas se você intercalar chamadas para registerRoute() e precacheAndRoute().

workbox-routing

O método setDefaultHandler() agora recebe um segundo parâmetro opcional correspondente ao método HTTP a que se aplica, com o valor padrão 'GET'.

• Se você usa setDefaultHandler() e todas as suas solicitações são GET, nenhuma mudança precisa ser feita.
• Se você tiver solicitações que não sejam GET (POST, PUT etc.), setDefaultHandler() não vai mais corresponder a essas solicitações.

Configuração do build

A opção mode para os modos getManifest e injectManifest em workbox-build e workbox-cli não deveria ser compatível 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 têm mais suporte para 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 com suporte.

Novas melhorias

estratégias de caixa de trabalho

A Workbox v6 apresenta uma nova maneira de os desenvolvedores externos definirem as próprias estratégias da Workbox. Isso garante que os desenvolvedores de terceiros possam estender o Workbox de acordo com as necessidades deles.

Nova classe base de estratégia

Na v6, todas as classes de estratégia do Workbox precisam estender a nova classe base Strategy. Todas as estratégias integradas foram reescritas para oferecer suporte a isso.

A classe de base Strategy é responsável por duas coisas principais:

• Invocar callbacks do ciclo de vida do plug-in comuns a todos os manipuladores de estratégia (por exemplo, quando eles começam, respondem e terminam).
• Criar uma instância "gerenciador", que possa gerenciar o estado de cada solicitação individual que uma estratégia está tratando.

Nova classe "handler"

Antes, tínhamos módulos internos chamados fetchWrapper e cacheWrapper, que, como o nome indica, agrupam as várias APIs de busca e cache com hooks no ciclo de vida. Esse é o mecanismo que permite que os plug-ins funcionem, mas não é exposto aos desenvolvedores.

A nova classe "handler", StrategyHandler, vai expor esses métodos para que as estratégias personalizadas possam chamar fetch() ou cacheMatch() e ter todos os plug-ins adicionados à instância de estratégia invocados automaticamente.

Essa classe também permitiria que os desenvolvedores adicionassem callbacks personalizados de ciclo de vida que podem ser específicos para as estratégias e que "apenas funcionam" com a interface de plug-in atual.

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 de /index.html acionar os callbacks requestWillFetch e cachedResponseWillBeUsed, eles não terão como se comunicar entre si ou mesmo saber que foram acionados pela mesma solicitação.

Na v6, todos os callbacks de 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 essa invocação de estratégia específica (ou seja, a chamada para handle()). Isso permite que os desenvolvedores criem 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 totalmente o estado do ciclo de vida do plug-in:

• handlerWillStart: é chamado antes que qualquer lógica de gerenciador comece 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 que o método handle() das estratégias retorne uma resposta. Esse callback pode ser usado para modificar essa resposta antes de retorná-la a um gerenciador de rotas ou outra lógica personalizada.
• handlerDidRespond: é chamado depois que o método handle() da estratégia retorna uma resposta. Esse callback pode ser usado para registrar todos os detalhes da resposta final, por exemplo, após mudanças feitas por outros plug-ins.
• handlerDidComplete: é chamado depois que todas as promessas de tempo de vida estendidas adicionadas ao evento da invocação desta estratégia forem resolvidas. Esse retorno de chamada pode ser usado para relatar quaisquer dados que precisem esperar até que o gerenciador seja concluído para fazer cálculos (por exemplo, status de ocorrência em cache, latência do cache, latência da rede).
• handlerDidError: é chamado se o gerenciador não conseguir fornecer uma resposta válida de nenhuma origem. Esse callback pode ser usado para fornecer conteúdo "alternativo" 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 callbacks. Tudo é tratado por uma nova classe base Strategy.

Tipos do TypeScript mais precisos para manipuladores

As definições do TypeScript para vários métodos de callback foram normalizadas. Isso deve levar a uma experiência melhor para os desenvolvedores que usam o TypeScript e escrevem o próprio código para implementar ou chamar manipuladores.

janela de caixa de trabalho

Novo método messageSkipEspereing()

Um novo método, messageSkipWaiting(), foi adicionado ao módulo workbox-window para simplificar o processo de ativação do service worker"aguardando". Isso oferece algumas melhorias:

• Ele chama postMessage() com o corpo de mensagem padrão de fato, {type: 'SKIP_WAITING'}, que um worker de serviço gerado pelo Workbox verifica para acionar skipWaiting().
• Ele escolhe o service worker "aguardando" correto para postar essa mensagem, mesmo que não seja o mesmo em que o workbox-window foi registrado.

Remoção de eventos "externos" em favor de uma propriedade isExternal

Todos os eventos "externos" em workbox-window foram removidos no lugar de 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 os desenvolvedores que não precisam saber podem ignorar a propriedade.

Receita mais limpa "Oferecer uma atualização de página para os usuários"

Graças às duas mudanças acima, a receita "Oferecer uma recarga de página aos usuários" pode ser simplificada:

MULTI_LINE_CODE_PLACEHOLDER_0

workbox-routing

Um novo parâmetro booleano, sameOrigin, é transmitido para a função matchCallback usada em workbox-routing. Ele é definido como true se a solicitação for para um URL de mesma origem e como "false", caso contrário.

Isso simplifica alguns modelos comuns:

MULTI_LINE_CODE_PLACEHOLDER_1

matchOptions em workbox-expiration

Agora você pode definir matchOptions em workbox-expiration, que vai ser transmitido como CacheQueryOptions para a chamada cache.delete(). A maioria dos desenvolvedores não precisa fazer isso.

workbox-precaching

Usa estratégias de workbox

O workbox-precaching foi reescrito para usar workbox-strategies como base. Isso não deve resultar em mudanças importantes e deve levar a uma melhor consistência a longo prazo na forma como os dois módulos acessam a rede e o cache.

O pré-cache agora processa as entradas uma por uma, não em massa

O workbox-precaching foi atualizado 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 as entradas em cache de uma só vez (deixando para o navegador descobrir como limitar esse processo).

Isso reduz a probabilidade de erros de net::ERR_INSUFFICIENT_RESOURCES durante a pré-cacheação e também reduz a contenção de largura de banda entre a pré-cacheação e as solicitações simultâneas feitas pelo app da Web.

O PrecacheFallbackPlugin permite uma substituição off-line mais fácil

Agora, workbox-precaching 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 "plano B" para uma determinada estratégia quando uma resposta não estiver disponível. O plug-in vai cuidar da construção adequada da chave de cache correta para o URL pré-armazenado em cache, incluindo qualquer parâmetro de revisão necessário.

Confira 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, ou seja, exibir uma página HTML personalizada off-line:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback no armazenamento em cache de execução

Se você estiver usando generateSW para criar um worker de serviço em vez de escrever o worker manualmente, use a nova opção de configuração precacheFallback em runtimeCaching para fazer a mesma coisa:

{
  // ... 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 receber ajuda

Acreditamos que a maioria das migrações será simples. Se você encontrar problemas não abordados neste guia, abra um problema no GitHub.