pré-armazenamento em cache da caixa de trabalho

Um recurso dos service workers é a capacidade de salvar um conjunto de arquivos no cache durante a instalação. Isso geralmente é chamado de "pré-armazenamento em cache", já que o conteúdo é armazenado em cache antes do service worker que está sendo usado.

O principal motivo para fazer isso é que isso dá aos desenvolvedores controle sobre o cache, o que significa que eles podem determinar quando e por quanto tempo um arquivo é armazenado em cache, além de disponibilizá-lo no navegador sem acessar a rede. Isso significa que ele pode ser usado para criar apps da Web que funcionam off-line.

O Workbox elimina grande parte do trabalho pesado do armazenamento prévio em cache simplificando a API e garantindo o download eficiente dos recursos.

Como funciona o pré-armazenamento em cache da caixa de trabalho

Quando um app da Web é carregado pela primeira vez, o workbox-precaching analisa todos os recursos que você quer transferir por download, remove as cópias e vincula os eventos relevantes do service worker para fazer o download e armazenar os recursos. Os URLs que já incluem informações de versão (como um hash de conteúdo) são usados como chaves de cache sem qualquer modificação adicional. Os URLs que não incluem informações de controle de versão têm um parâmetro de consulta de URL extra anexado à chave de cache que representa um hash do conteúdo gerado pelo Workbox no tempo de build.

workbox-precaching faz tudo isso durante o evento install do service worker.

Quando um usuário acessar novamente seu app da Web e você tiver um novo service worker com recursos pré-armazenados em cache diferentes, o workbox-precaching vai analisar a nova lista e determinar quais recursos são completamente novos e quais dos recursos atuais precisam ser atualizados com base na revisão. Novos recursos ou atualizações de revisões serão adicionados ao cache durante o evento install do novo service worker.

Esse novo service worker não será usado para responder a solicitações até que o evento activate seja acionado. No evento activate, workbox-precaching verifica se há recursos armazenados em cache que não estejam mais na lista de URLs atuais e os remove do cache.

O workbox-precaching executará essas etapas sempre que o service worker estiver instalado e ativado, garantindo que o usuário tenha os recursos mais recentes e fazendo o download apenas dos arquivos que foram alterados.

Exibição de respostas pré-armazenadas em cache

Chamar precacheAndRoute() ou addRoute() cria uma rota que corresponde às solicitações de URLs armazenados em cache.

A estratégia de resposta utilizada nessa rota é cache-first: a resposta pré-armazenada em cache será usada, a menos que a resposta armazenada em cache não esteja presente (devido a algum erro inesperado). Nesse caso, uma resposta de rede será usada.

A ordem em que você chama precacheAndRoute() ou addRoute() é importante. Normalmente, é melhor chamá-lo no início do arquivo do service worker, antes de registrar outras rotas com registerRoute(). Se você chamou registerRoute() primeiro e essa rota correspondeu a uma solicitação recebida, qualquer estratégia definida nessa rota adicional será usada para responder, em vez da estratégia que prioriza o cache usada por workbox-precaching.

Explicação da lista de pré-cache

O workbox-precaching espera uma matriz de objetos com as propriedades url e revision. Essa matriz às vezes é chamada de manifesto de pré-cache:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([
  {url: '/index.html', revision: '383676'},
  {url: '/styles/app.0c9a31.css', revision: null},
  {url: '/scripts/app.0d5770.js', revision: null},
  // ... other entries ...
]);

Essa lista faz referência a um conjunto de URLs, cada um com as próprias informações de "revisão".

Para o segundo e o terceiro objetos do exemplo acima, a propriedade revision é definida como null. Isso ocorre porque as informações de revisão estão no próprio URL, o que geralmente é uma prática recomendada para recursos estáticos.

O primeiro objeto (/index.html) define explicitamente uma propriedade de revisão, que é um hash gerado automaticamente do conteúdo do arquivo. Ao contrário dos recursos JavaScript e CSS, os arquivos HTML geralmente não podem incluir informações de revisão nos URLs. Caso contrário, os links para esses arquivos na Web seriam corrompidos sempre que o conteúdo da página fosse alterado.

Ao transmitir uma propriedade de revisão para precacheAndRoute(), o Workbox pode saber quando o arquivo mudou e fazer as atualizações necessárias.

O Workbox inclui ferramentas que ajudam a gerar essa lista:

• workbox-build: é um pacote de nós que pode ser usado em uma tarefa gulp ou como um script de execução de npm.
• workbox-webpack-plugin: os usuários do webpack podem usar este plug-in.
• workbox-cli: nossa CLI também pode ser usada para gerar a lista de recursos e adicioná-los ao service worker.

Solicitações recebidas para arquivos pré-armazenados em cache

Uma coisa que workbox-precaching faz imediatamente é manipular as solicitações de rede recebidas para tentar corresponder arquivos pré-armazenados em cache. Isso se adapta às práticas comuns na Web.

Por exemplo, uma solicitação para / geralmente pode ser atendida pelo arquivo em /index.html.

Abaixo está a lista de manipulações que workbox-precaching executa por padrão e como é possível alterar esse comportamento.

Ignorar parâmetros de URL

As solicitações com parâmetros de pesquisa podem ser alteradas para remover valores específicos ou todos os valores.

Por padrão, os parâmetros de pesquisa que começam com utm_ ou correspondem exatamente a fbclid são removidos, o que significa que uma solicitação de /about.html?utm_campaign=abcd será atendida com uma entrada pré-armazenada em cache para /about.html.

Você pode ignorar um conjunto diferente de parâmetros de pesquisa usando ignoreURLParametersMatching:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    // Ignore all URL parameters.
    ignoreURLParametersMatching: [/.*/],
  }
);

Índice do diretório

Por padrão, as solicitações que terminam em / vão ser correspondidas com entradas com um index.html anexado ao final. Isso significa que uma solicitação de entrada para / pode ser processada automaticamente com a entrada /index.html armazenada em cache.

É possível alterar isso para outra coisa ou desativá-lo completamente, definindo directoryIndex:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    directoryIndex: null,
  }
);

Limpar URLs

Se uma solicitação não corresponder ao pré-cache, vamos adicionar .html no final para oferecer suporte a URLs "limpos" (também conhecidos como URLs "bonitos"). Isso significa que uma solicitação como /about será processada pela entrada pré-armazenada em cache para /about.html.

Você pode desativar esse comportamento definindo cleanUrls:

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute([{url: '/about.html', revision: 'b79cd4'}], {
  cleanUrls: false,
});

Manipulações personalizadas

Se você quiser definir correspondências personalizadas de solicitações recebidas para recursos armazenados previamente em cache, poderá fazer isso com a opção urlManipulation. É um callback que retorna uma matriz de possíveis correspondências.

import {precacheAndRoute} from 'workbox-precaching';

precacheAndRoute(
  [
    {url: '/index.html', revision: '383676'},
    {url: '/styles/app.0c9a31.css', revision: null},
    {url: '/scripts/app.0d5770.js', revision: null},
  ],
  {
    urlManipulation: ({url}) => {
      // Your logic goes here...
      return [alteredUrlOption1, alteredUrlOption2];
    },
  }
);

Uso avançado

Como usar o PrecacheController diretamente

Por padrão, o workbox-precaching configura os listeners install e activate automaticamente. Para desenvolvedores familiarizados com service workers, isso pode não ser a opção ideal se você precisa de mais controle.

Em vez de usar a exportação padrão, é possível usar o PrecacheController diretamente para adicionar itens ao pré-cache, determinar quando esses recursos serão instalados e quando a limpeza precisa ocorrer.

import {PrecacheController} from 'workbox-precaching';

const precacheController = new PrecacheController();
precacheController.addToCacheList([
  {url: '/styles/example-1.abcd.css', revision: null},
  {url: '/styles/example-2.1234.css', revision: null},
  {url: '/scripts/example-1.abcd.js', revision: null},
  {url: '/scripts/example-2.1234.js', revision: null},
]);

precacheController.addToCacheList([{
  url: '/index.html',
  revision: 'abcd',
}, {
  url: '/about.html',
  revision: '1234',
}]);

self.addEventListener('install', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.install(event));
});

self.addEventListener('activate', (event) => {
  // Passing in event is required in Workbox v6+
  event.waitUntil(precacheController.activate(event));
});

self.addEventListener('fetch', (event) => {
  const cacheKey = precacheController.getCacheKeyForURL(event.request.url);
  event.respondWith(caches.match(cacheKey).then(...));
});

Leitura direta de recursos pré-armazenados em cache

Há momentos em que talvez seja necessário ler um recurso pré-armazenado em cache diretamente, fora do contexto do roteamento que workbox-precaching pode executar automaticamente. Por exemplo, é possível pré-armazenar em cache modelos HTML parciais que precisam ser recuperados e usados na criação de uma resposta completa.

Em geral, é possível usar a API Cache Storage para acessar os objetos Response pré-armazenados em cache, mas há uma quebra: a chave de cache do URL que precisa ser usada ao chamar cache.match() pode conter um parâmetro de controle de versão que workbox-precaching cria e mantém automaticamente.

Para conseguir a chave de cache correta, chame getCacheKeyForURL(), transmitindo o URL original e, em seguida, use o resultado para executar um cache.match() no cache apropriado.

import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';

const cache = await caches.open(cacheNames.precache);
const response = await cache.match(getCacheKeyForURL('/precached-file.html'));

Como alternativa, se você só precisa do objeto Response pré-armazenado em cache, chame matchPrecache(), que vai usar automaticamente a chave de cache correta e pesquisar no cache correto:

import {matchPrecache} from 'workbox-precaching';

const response = await matchPrecache('/precached-file.html');

Limpar pré-caches antigos

A maioria das versões do Workbox mantém o mesmo formato para armazenar dados pré-armazenados em cache, e os pré-caches criados por versões mais antigas do Workbox geralmente podem ser usados no estado em que se encontram em versões mais recentes. No entanto, raramente ocorre uma alteração interruptiva no armazenamento de pré-armazenamento em cache que exija que os usuários façam o download de tudo novamente, o que torna obsoletos os dados pré-armazenados em cache anteriormente. Essa mudança ocorreu entre as versões do Workbox v3 e v4.

Esses dados obsoletos não interferem nas operações normais, mas contribuem para o uso geral da cota de armazenamento. Além disso, pode ser mais fácil para os usuários excluí-los explicitamente. É possível fazer isso adicionando cleanupOutdatedCaches() ao service worker ou definindo cleanupOutdatedCaches: true se você estiver usando uma das ferramentas de build do Workbox para gerar o service worker.

Como usar a integridade de recursos secundários

Alguns desenvolvedores podem querer as garantias extras oferecidas pela aplicação da integridade de sub-recursos ao recuperar URLs pré-armazenados em cache da rede.

Uma outra propriedade opcional chamada integrity pode ser adicionada a qualquer entrada no manifesto de pré-cache. Se fornecido, ele será usado como o valor integrity ao construir o Request usado para preencher o cache. Se houver uma incompatibilidade, o processo de pré-armazenamento em cache falhará.

Determinar quais entradas de manifesto de pré-cache precisam ter propriedades integrity e descobrir os valores apropriados a serem usados está fora do escopo das ferramentas de build do Workbox. Em vez disso, os desenvolvedores que quiserem ativar essa funcionalidade precisarão modificar o manifesto de pré-cache gerado pelo Workbox para adicionar as informações apropriadas. A opção manifestTransform na configuração de ferramentas de build do Workbox pode ajudar a:

const ssri = require('ssri');

const integrityManifestTransform = (originalManifest, compilation) => {
  const warnings = [];
  const manifest = originalManifest.map(entry => {
    // If some criteria match:
    if (entry.url.startsWith('...')) {
      // This has to be a synchronous function call, for example:
      // compilation will be set when using workbox-webpack-plugin.
      // When using workbox-build directly, you can read the file's
      // contents from disk using, e.g., the fs module.
      const asset = compilation.getAsset(entry.url);
      entry.integrity = ssri.fromData(asset.source.source()).toString();

      // Push a message to warnings if needed.
    }
    return entry;
  });

  return {warnings, manifest};
};

// Then add manifestTransform: [integrityManifestTransform]
// to your Workbox build configuration.

workbox-precaching.urlManipulation(
  { url }: object,
)

workbox-precaching.addPlugins(
  plugins: WorkboxPlugin[],
)

workbox-precaching.addRoute(
  options?: PrecacheRouteOptions,
)

workbox-precaching.cleanupOutdatedCaches()

workbox-precaching.createHandlerBoundToURL(
  url: string,
)

workbox-precaching.getCacheKeyForURL(
  url: string,
)

workbox-precaching.matchPrecache(
  request: string | Request,
)

workbox-precaching.precache(
  entries: (string | PrecacheEntry)[],
)

workbox-precaching.precacheAndRoute(
  entries: (string | PrecacheEntry)[],
  options?: PrecacheRouteOptions,
)