Esta página foi traduzida pela API Cloud Translation.

Migrar do Workbox v2 para a v3

Este guia se concentra em alterações interruptivas introduzidas no Workbox v3, com exemplos das mudanças que você precisaria fazer ao fazer upgrade de uma configuração da Workbox v2.

Se você usa a combinação legada de sw-precache/sw-toolbox e quer fazer a transição para o Workbox pela primeira vez, consulte este guia de migração.

Contexto da v3

A versão v3 do Workbox representa uma refatoração significativa da base de código existente. Os objetivos principais são:

Minimize o tamanho da caixa de trabalho. A quantidade de código de ambiente de execução do service worker que é baixada e executada foi reduzida. Em vez de permitir que todos os usuários participem de um pacote monolítico, apenas o código dos recursos específicos que você está usando será importado no ambiente de execução.
O Workbox tem uma CDN. Oferecemos uma hospedagem CDN totalmente compatível e baseada no Google Cloud Storage como a opção canônica para acessar as bibliotecas de ambiente de execução do Workbox, facilitando a implementação e a execução do Workbox.
Melhorias na depuração e nos registros. A experiência de depuração e geração de registros foi bastante aprimorada. Os registros de depuração são ativados por padrão sempre que a caixa de trabalho é usada de uma origem localhost e todos os registros e declarações são removidos dos builds de produção.
Plug-in webpack melhorado. O workbox-webpack-plugin se integra melhor ao processo de build do webpack, o que permite um caso de uso sem configuração quando você quer pré-armazenar todos os recursos no pipeline de build em cache.

Para atingir essas metas e limpar alguns aspectos da interface anterior que pareciam estranhos ou levavam a antipadrões, exigiu a introdução de uma série de alterações interruptivas na versão v3.

Alterações importantes

Configuração do build

As mudanças abaixo afetam o comportamento de todas as nossas ferramentas de build (workbox-build, workbox-cli, workbox-webpack-plugin), que compartilham um conjunto comum de opções de configuração.

O nome do gerenciador 'fastest' era válido anteriormente e era tratado como um alias para 'staleWhileRevalidate' durante a configuração de runtimeCaching. Ela não é mais válida, e os desenvolvedores precisam passar a usar 'staleWhileRevalidate' diretamente.
Vários nomes de propriedades runtimeCaching.options foram atualizados e há uma validação de parâmetro adicional em vigor que vai causar a falha de um build se uma configuração inválida for usada. Consulte a documentação de runtimeCaching para uma lista das opções compatíveis no momento.

workbox-background-sync

O parâmetro de configuração maxRetentionTime agora é interpretado como um número de minutos, não de milissegundos.
Agora há uma string obrigatória, que representa o nome da fila, que deve ser transmitida como o primeiro parâmetro ao construir o plug-in ou a classe autônoma. Antes ela era transmitida como uma propriedade das opções. Consulte a documentação da plataforma atualizada da API.

workbox-broadcast-cache-update

Agora há uma string obrigatória, que representa o nome do canal, que deve ser transmitida como o primeiro parâmetro ao construir o plug-in ou a classe autônoma.

Por exemplo, na v2, você inicializaria a classe do plug-in da seguinte maneira:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

O uso equivalente na v3 é:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

Consulte a documentação da plataforma atualizada da API.

workbox-build

Por padrão, a correspondência do padrão glob será realizada com as opções follow: true (que seguirão links simbólicos) e strict: true (que é menos tolerante a erros "incomuns"). Você pode desativar qualquer um deles e retornar ao comportamento anterior definindo globFollow: false e/ou globStrict: false na configuração do build.
Todas as funções em workbox-build retornam uma propriedade adicional, warnings, nas respostas retornadas. Alguns cenários que eram tratados como erros fatais na v2 agora são permitidos, mas informados via warnings, que é uma matriz de strings.

Na v2, você pode chamar generateSW da seguinte forma:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
  .catch((error) => console.error(`Something went wrong: ${error}`));

Embora seja possível usar o mesmo código na v3, é uma boa ideia verificar se há warnings e registrá-los:

const workboxBuild = require('workbox-build');

workboxBuild.generateSW({...})
  .then(({count, size, warnings}) => {
    for (const warning of warnings) {
      console.warn(warning);
    }
    console.log(`Precached ${count} files, totalling ${size} bytes.`);
  })
  .catch((error) => console.error(`Something went wrong: ${error}`));

Os desenvolvedores que criaram as próprias funções ManifestTransform personalizadas na v2 precisam retornar a matriz de manifesto em um objeto (ou seja, em vez de return manifestArray;, use return {manifest: manifestArray};). Isso permite que seu plug-in inclua uma propriedade warnings opcional, que precisa ser uma matriz de strings contendo informações de aviso não fatais.

Se você estava escrevendo um ManifestTransform personalizado na v2, o código seria como:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

tem um equivalente v3 de:

const cdnTransform = manifestEntries => {
  const manifest = manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
  return {manifest, warnings: []};
};

A função getFileManifestEntries() foi renomeada como getManifest(), e a promessa retornada agora inclui mais informações sobre os URLs que são pré-armazenados em cache.

Código como o seguinte na v2:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

pode ser reescrito na v3 como:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

A função generateFileManifest() foi removida. Em vez disso, recomendamos que os desenvolvedores chamem getManifest() e usem a resposta dela para gravar dados no disco no formato apropriado.

workbox-cache-expiration

A API do plug-in permaneceu a mesma, que é o modo que a maioria dos desenvolvedores acabará usando. No entanto, há mudanças significativas na API que afetam os desenvolvedores que a usam como uma classe autônoma. Consulte a documentação da plataforma atualizada da API.

workbox-cli

Os desenvolvedores podem executar a CLI com a flag --help para um conjunto completo de parâmetros compatíveis.

O suporte para o alias workbox-cli para o script binário foi removido. O binário agora só pode ser acessado como workbox.
Os comandos da v2 generate:sw e inject:manifest foram renomeados como generateSW e injectManifest na v3.
Na v2, o arquivo de configuração padrão (usado quando não era fornecido explicitamente) era workbox-cli-config.js no diretório atual. Na v3, é workbox-config.js.

Considerados em conjunto, isso significa que na v2:

$ workbox inject:manifest

executaria o comando "inject manifesto" processo de build, usando uma configuração lida de workbox-cli-config.js e na v3:

$ workbox injectManifest

vai fazer o mesmo, mas vai ler a configuração de workbox-config.js.

pré-armazenamento em cache na caixa de trabalho

Anteriormente, o método precache() executava as modificações de cache e configurou o roteamento para exibir entradas em cache. Agora, o precache() só modifica as entradas de cache, e um novo método, addRoute(), foi exposto para registrar uma rota a fim de exibir essas respostas em cache. Os desenvolvedores que quiserem a funcionalidade "dois em um" anterior podem mudar para chamar precacheAndRoute().
Várias opções que eram configuradas pelo construtor WorkboxSW agora são transmitidas como o parâmetro options no workbox.precaching.precacheAndRoute([...], options). Quando não configuradas, os padrões dessas opções estão listados nos documentos de referência.
Por padrão, os URLs sem extensão de arquivo serão automaticamente verificados quanto à correspondência com uma entrada de cache que contenha uma extensão .html. Por exemplo, se uma solicitação for feita para /path/to/index (que não está pré-armazenada em cache) e houver uma entrada pré-armazenada em cache para /path/to/index.html, essa entrada será usada. Os desenvolvedores podem desativar esse novo comportamento definindo {cleanUrls: false} ao transmitir opções para workbox.precaching.precacheAndRoute().
O workbox-broadcast-update não será mais configurado automaticamente para anunciar atualizações de cache para recursos pré-armazenados em cache.

O código a seguir na v2:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

tem um equivalente v3 de:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

roteamento de caixa de trabalho

Os desenvolvedores que usavam o workbox-routing com o namespace workbox.router.* de um objeto WorkboxSW precisam mudar para o novo namespace workbox.routing.*.
As rotas agora são avaliadas em uma ordem de "primeiro registrado-vitória". Essa é a ordem oposta da avaliação de Route usada na v2, em que o último Route registrado teria prioridade.
A classe ExpressRoute e suporte para "estilo Express" os caracteres curinga foram removidos. Isso reduz consideravelmente o tamanho do workbox-routing. As strings usadas como o primeiro parâmetro para workbox.routing.registerRoute() agora serão tratadas como correspondências exatas. As correspondências parciais ou curinga precisam ser processadas por RegExps. O uso de qualquer RegExp que corresponda a todo ou parte do URL da solicitação pode acionar uma rota.
O método auxiliar addFetchListener() da classe Router foi removido. Os desenvolvedores podem adicionar o próprio gerenciador fetch explicitamente ou usar a interface fornecida por workbox.routing, que cria um gerenciador fetch implicitamente para eles.
Os métodos registerRoutes() e unregisterRoutes() foram removidos. As versões desses métodos que operam em uma única Route não foram alteradas, e os desenvolvedores que precisam registrar ou cancelar o registro de várias rotas de uma vez precisam fazer uma série de chamadas para registerRoute() ou unregisterRoute().

O código a seguir na v2:

const workboxSW = new self.WorkboxSW();

workboxSW.router.registerRoute(
  '/path/with/.*/wildcard/',
  workboxSW.strategies.staleWhileRevalidate()
);

workboxSW.router.registerRoute(
  new RegExp('^https://example.com/'),
  workboxSW.strategies.networkFirst()
);

tem um equivalente v3 de:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

Estratégias de caixa de trabalho (antes conhecidas como workbox-runtime-caching)

O módulo workbox-runtime-caching agora é oficialmente conhecido como workbox-strategies e foi publicado em npm com seu novo nome.
Usar a expiração do cache em uma estratégia sem fornecer também um nome de cache não é mais válido. Na v2, isso era possível:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

Isso levaria à expiração de entradas no cache padrão, o que é inesperado. Na v3, um nome de cache é obrigatório:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

O método de ciclo de vida cacheWillMatch foi renomeado para cachedResponseWillBeUsed. Essa não será uma mudança visível para os desenvolvedores, a menos que eles tenham criado os próprios plug-ins que reagiram à cacheWillMatch.
A sintaxe para especificar plug-ins ao configurar uma estratégia mudou. Cada plug-in precisa ser listado explicitamente na propriedade plugins da configuração da estratégia.

O código a seguir na v2:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

tem um equivalente v3 de:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

Você pode saber mais em "Como usar plug-ins" guia.

workbox-sw

Internamente, o workbox-sw foi reescrito para ser um "carregador" leve. , que requer uma configuração básica e é responsável por extrair os outros módulos necessários no ambiente de execução. Em vez de criar uma nova instância da classe WorkboxSW, os desenvolvedores vão interagir com uma instância que é exposta automaticamente no namespace global.

Anteriormente na v2:

importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');

const workbox = new WorkboxSW({
  skipWaiting: true,
  clientsClaim: true,
  // etc.
});

workbox.router.registerRoute(...);

Na v3, basta importar o script workbox-sw.js, e uma instância pronta para uso será disponibilizada automaticamente no namespace global como workbox:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

skipWaiting e clientsClaim não são mais opções transmitidas para o construtor WorkboxSW. Em vez disso, eles foram alterados para os métodos workbox.clientsClaim() e workbox.skipWaiting().
A opção handleFetch, que anteriormente tinha suporte no construtor da v2, não é mais compatível na v3. Os desenvolvedores que precisam de uma funcionalidade semelhante para testar o service worker sem que nenhum gerenciador de busca seja invocado podem usar "Bypass for network" (Ignorar para a rede). disponível nas Ferramentas para desenvolvedores do Chrome.

A opção "Bypass for Network" no Chrome DevTools.

workbox-webpack-plugin

O plug-in foi substancialmente reescrito e, em muitos casos, pode ser usado sem configuração. modo Consulte a documentação da plataforma atualizada da API.

Agora, a API expõe duas classes, GenerateSW e InjectManifest. Isso torna a alternância entre os modos explícita, em comparação com o comportamento da v2, em que o comportamento mudou com base na presença de swSrc.
Por padrão, os recursos no pipeline de compilação do webpack são pré-armazenados em cache, e não é mais necessário configurar o globPatterns. O único motivo para continuar usando globPatterns é se você precisar pré-armazenar em cache recursos que não estão incluídos no seu build do webpack. Em geral, ao migrar para o plug-in v3, comece removendo toda a configuração anterior baseada em glob e adicione-a novamente apenas se você precisar dela.

Receber ajuda

Acreditamos que a maioria das migrações será simples. Se você tiver problemas que não foram abordados neste guia, abra um problema (link em inglês) no GitHub.