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

• Documentos HTML entre origens para URLs que correspondem a um redirecionamento HTTP não podem mais ser usados para atender 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. Em vez disso, 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, não é necessário fazer mudanças.
• Se você tiver solicitações que não sejam GET (POST, PUT etc.), setDefaultHandler() não vai mais fazer com que essas solicitações sejam correspondentes.

Configuração do build

A opção mode para os modos getManifest e injectManifest em workbox-build e workbox-cli não tinha 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 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

workbox-strategies

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 de "gerenciador", que pode gerenciar o estado de cada solicitação individual que uma estratégia está processando.

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 de 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 de ciclo de vida personalizados 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

Na 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, esses dois callbacks não terão como se comunicar entre si nem saberão 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

Foram adicionados novos callbacks de ciclo de vida de plug-ins 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 extensão de tempo de vida adicionadas ao evento da invocação desta estratégia forem resolvidas. Esse callback pode ser usado para informar sobre todos os dados que precisam esperar até que o gerenciador seja concluído para calcular (por exemplo, status de ocorrência em cache, latência do cache, latência de 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.

workbox-window

Novo método messageSkipWaiting()

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 service worker 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:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

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:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

matchOptions em workbox-expiration

Agora é possível definir matchOptions em workbox-expiration, que 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 elas em cache de uma só vez (deixando que o navegador descubra como limitar).

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

O 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 "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:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

precacheFallback no armazenamento em cache no tempo 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

A maioria das migrações é simples. Se você encontrar problemas não abordados neste guia, registre um problema no GitHub.