workbox-webpack-plugin

O Workbox fornece dois plug-ins do webpack: um que gera um service worker completo para você e outro que gera uma lista de recursos para pré-cache que é injetada em um arquivo de service worker.

Os plug-ins são implementados como duas classes no módulo workbox-webpack-plugin, chamadas GenerateSW e InjectManifest. As respostas para as perguntas a seguir podem ajudar você a escolher o plug-in e a configuração corretos.

Qual plug-in usar

GenerateSW

O plug-in GenerateSW vai criar um arquivo de service worker para você e adicionar ao pipeline de recursos do webpack.

Quando usar GenerateSW

  • Você quer pré-cachear arquivos.
  • Você tem necessidades simples de armazenamento em cache de execução.

Quando NÃO usar GenerateSW

  • Você quer usar outros recursos do Service Worker (por exemplo, Web Push).
  • Você quer importar outros scripts ou adicionar mais lógica para estratégias de armazenamento em cache personalizadas.

InjectManifest

O plug-in InjectManifest vai gerar uma lista de URLs para pré-armazenamento em cache e adicionar esse manifesto de pré-armazenamento em cache a um arquivo de service worker existente. Caso contrário, o arquivo vai permanecer como está.

Quando usar InjectManifest

  • Você quer ter mais controle sobre o worker do serviço.
  • Você quer pré-cachear arquivos.
  • Você precisa personalizar o roteamento e as estratégias.
  • você quiser usar seu service worker com outros recursos da plataforma (por exemplo, Web Push).

Quando NÃO usar InjectManifest

  • Você quer o caminho mais fácil para adicionar um service worker ao seu site.

Plug-in GenerateSW

É possível adicionar o plug-in GenerateSW à configuração do webpack desta forma:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

Isso vai gerar um service worker com a configuração de pré-armazenamento em cache de todos os recursos do webpack coletados pela configuração e as regras de armazenamento em cache de execução fornecidas.

Um conjunto completo de opções de configuração pode ser encontrado na documentação de referência.

Plug-in InjectManifest

É possível adicionar o plug-in InjectManifest à configuração do webpack desta forma:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

Isso criará um manifesto de pré-cache baseado nos recursos de webpack coletados pela sua configuração e o injetará no arquivo do service worker empacotado e compilado.

Um conjunto completo de opções de configuração pode ser encontrado na documentação de referência.

Informações extras

Confira orientações sobre o uso dos plug-ins no contexto de um build maior do webpack na seção "Aplicativo da Web progressivo" da documentação do webpack.

Tipos

GenerateSW

Essa classe oferece suporte à criação de um novo arquivo de worker de serviço pronto para uso como parte do processo de compilação do webpack.

Use uma instância de GenerateSW na matriz plugins de uma configuração do webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

Propriedades

GenerateSWConfig

Propriedades

  • additionalManifestEntries

    (string | ManifestEntry)[] opcional

    Uma lista de entradas a serem pré-armazenadas em cache, além de todas as entradas geradas como parte da configuração do build.

  • babelPresetEnvTargets

    string[] opcional

    O valor padrão é: ["chrome >= 56"]

    Os destinos a serem transmitidos para babel-preset-env ao transcompilar o pacote do service worker.

  • cacheId

    string opcional

    Um ID opcional a ser anexado aos nomes do cache. Isso é útil principalmente para desenvolvimento local, em que vários sites podem ser veiculados da mesma origem http://localhost:port.

  • pedaços

    string[] opcional

    Um ou mais nomes de blocos cujos arquivos de saída correspondentes precisam ser incluídos no manifesto de pré-cache.

  • cleanupOutdatedCaches

    booleano opcional

    O valor padrão é false.

    Define se o Workbox precisa ou não tentar identificar e excluir as pré-caches criadas por versões mais antigas e incompatíveis.

  • clientsClaim

    booleano opcional

    O valor padrão é false.

    Indica se o service worker precisa ou não iniciar o controle de clientes existentes assim que for ativado.

  • directoryIndex

    string opcional

    Se uma solicitação de navegação para um URL que termina em / não corresponder a um URL pré-armazenado, esse valor será anexado ao URL, que será verificado quanto a uma correspondência de pré-cache. Ele precisa ser definido como o que o servidor da Web está usando para o índice de diretórios.

  • disableDevLogs

    booleano opcional

    O valor padrão é false.

  • dontCacheBustURLsMatching

    RegExp opcional

    Os recursos que corresponderem a esse valor serão considerados como tendo uma versão exclusiva pelo URL e serão dispensados da quebra de cache HTTP normal que é feita ao preencher o pré-cache. Embora não seja obrigatório, se o processo de build já insere um valor [hash] em cada nome de arquivo, forneça uma RegExp que detecte isso, já que ela reduz a largura de banda consumida durante a pré-cacheação.

  • excluir

    (string | RegExp | function)[] opcional

    Um ou mais especificadores usados para excluir recursos do manifesto de pré-cache. Isso é interpretado seguindo as mesmas regras como a opção exclude padrão do webpack. Se nenhum valor for fornecido, o padrão será [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] opcional

    Um ou mais nomes de blocos com arquivos de saída correspondentes que precisam ser excluídos do manifesto de pré-cache.

  • ignoreURLParametersMatching

    RegExp[] opcional

    Todos os nomes de parâmetro de pesquisa que corresponderem a uma das regex nessa matriz serão removidos antes de procurar uma correspondência de pré-cache. Isso é útil se os usuários solicitarem URLs que contêm, por exemplo, parâmetros de URL usados para rastrear a origem do tráfego. Se nenhum valor for fornecido, o padrão será [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opcional

    Uma lista de arquivos JavaScript que precisam ser transmitidos para importScripts() no arquivo do service worker gerado. Isso é útil quando você quer permitir que o Workbox crie seu arquivo do service worker de nível superior, mas quer incluir algum código extra, como um listener de eventos de push.

  • importScriptsViaChunks

    string[] opcional

    Um ou mais nomes de blocos do webpack. O conteúdo desses blocos será incluído no worker de serviço gerado por uma chamada para importScripts().

  • incluem

    (string | RegExp | function)[] opcional

    Um ou mais especificadores usados para incluir recursos no manifesto de pré-cache. Isso é interpretado seguindo as mesmas regras como a opção include padrão do webpack.

  • inlineWorkboxRuntime

    booleano opcional

    O valor padrão é false.

    Se o código de execução da biblioteca Workbox precisa ser incluído no service worker de nível superior ou dividido em um arquivo separado que precisa ser implantado com o service worker. Manter o ambiente de execução separado significa que os usuários não precisarão fazer o download do código do Workbox toda vez que o service worker de nível superior mudar.

  • manifestEntries

    ManifestEntry[] opcional

  • manifestTransforms

    ManifestTransform[] opcional

    Uma ou mais funções que serão aplicadas sequencialmente ao manifesto gerado. Se modifyURLPrefix ou dontCacheBustURLsMatching também forem especificados, as transformações correspondentes serão aplicadas primeiro.

  • maximumFileSizeToCacheInBytes

    número opcional

    O valor padrão é: 2097152

    Esse valor pode ser usado para determinar o tamanho máximo dos arquivos que serão armazenados previamente em cache. Isso evita que você pré-cacheie acidentalmente arquivos muito grandes que podem ter sido combinados acidentalmente com um dos seus padrões.

  • modo

    string opcional

    Se definido como "production", um pacote de service worker otimizado que exclui informações de depuração será produzido. Se não for configurado explicitamente aqui, o valor mode configurado na compilação webpack atual será usado.

  • modifyURLPrefix

    objeto opcional

    Um objeto que mapeia prefixos de string para valores de string de substituição. Isso pode ser usado para, por exemplo, remover ou adicionar um prefixo de caminho de uma entrada de manifesto se a configuração de hospedagem da Web não corresponder à configuração do sistema de arquivos local. Como alternativa com mais flexibilidade, use a opção manifestTransforms e forneça uma função que modifique as entradas no manifesto usando qualquer lógica que você fornecer.

    Exemplo de uso:

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    string opcional

    O valor padrão é: null

    Se especificado, todas as solicitações de navegação para URLs que não estão pré-armazenados em cache serão atendidas com o HTML no URL fornecido. É preciso transmitir o URL de um documento HTML listado no manifesto de pré-cache. Isso é usado em um cenário de app de página única, em que você quer que todas as navegações usem um HTML de shell de app comum.

  • navigateFallbackAllowlist

    RegExp[] opcional

    Uma matriz opcional de expressões regulares que restringe a quais URLs o comportamento navigateFallback configurado se aplica. Isso é útil se apenas um subconjunto dos URLs do seu site precisar ser tratado como parte de um app de página única. Se navigateFallbackDenylist e navigateFallbackAllowlist estiverem configurados, a lista de negação terá precedência.

    Observação: essas RegExps podem ser avaliadas em relação a cada URL de destino durante uma navegação. Evite usar RegExps complexas, senão os usuários vão notar atrasos ao navegar pelo site.

  • navigateFallbackDenylist

    RegExp[] opcional

    Uma matriz opcional de expressões regulares que restringe a quais URLs o comportamento navigateFallback configurado se aplica. Isso é útil se apenas um subconjunto dos URLs do seu site precisar ser tratado como parte de um app de página única. Se navigateFallbackDenylist e navigateFallbackAllowlist estiverem configurados, a lista de bloqueio terá precedência.

    Observação: essas RegExps podem ser avaliadas em relação a cada URL de destino durante uma navegação. Evite usar RegExps complexas, senão os usuários vão notar atrasos ao navegar pelo site.

  • navigationPreload

    booleano opcional

    O valor padrão é: false

    Define se o carregamento prévio de navegação vai ser ativado ou não no service worker gerado. Quando definido como "true", também é necessário usar runtimeCaching para configurar uma estratégia de resposta adequada que corresponda a solicitações de navegação e use a resposta pré-carregada.

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions opcional

    O valor padrão é false.

    Controla se o suporte ao Google Analytics off-line será incluído ou não. Quando true, a chamada para initialize() de workbox-google-analytics será adicionada ao service worker gerado. Quando definido como Object, esse objeto é transmitido para a chamada initialize(), permitindo que você personalize o comportamento.

  • runtimeCaching

    RuntimeCaching[] opcional

    Ao usar as ferramentas de build do Workbox para gerar o worker de serviço, é possível especificar uma ou mais configurações de armazenamento em cache do ambiente de execução. Em seguida, elas são convertidas em chamadas workbox-routing.registerRoute usando a configuração de correspondência e gerenciador definida por você.

    Para conferir todas as opções, consulte a documentação do workbox-build.RuntimeCaching. O exemplo abaixo mostra uma configuração típica, com duas rotas de execução definidas:

  • skipWaiting

    booleano opcional

    O valor padrão é false.

    Define se uma chamada incondicional para skipWaiting() será adicionada ao service worker gerado. Se false, um listener message será adicionado, permitindo que as páginas do cliente acionem skipWaiting() chamando postMessage({type: 'SKIP_WAITING'}) em um worker de serviço em espera.

  • sourcemap

    booleano opcional

    O valor padrão é true.

    Define se é necessário criar um sourcemap para os arquivos de service worker gerados.

  • swDest

    string opcional

    O valor padrão é: "service-worker.js"

    O nome do recurso do arquivo do service worker criado por este plug-in.

InjectManifest

Essa classe oferece suporte à compilação de um arquivo de service worker fornecido por swSrc e injeta nele uma lista de URLs e informações de revisão para pré-cacheamento com base no pipeline de recursos do webpack.

Use uma instância de InjectManifest na matriz plugins de uma configuração do webpack.

Além de injetar o manifesto, esse plug-in vai realizar uma compilação do arquivo swSrc, usando as opções da configuração principal do webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

Propriedades

Propriedades

default

Tipo

objeto

Propriedades

  • GenerateSW

    consulta

  • InjectManifest

    consulta