workbox-webpack-plugin

O Workbox oferece dois plug-ins webpack: um que gera um service worker completo para você e outro que gera uma lista de recursos para pré-armazenar em cache que é injetado 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 às perguntas a seguir podem ajudar você a escolher o plug-in e a configuração certos para usar.

Qual plug-in usar

GenerateSW

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

Quando usar GenerateSW

  • Você quer pré-armazenar em cache os arquivos.
  • você tiver necessidades simples de armazenamento em cache no ambiente 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 lógica para estratégias personalizadas de armazenamento em cache.

InjectManifest

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

Quando usar InjectManifest

  • Você quer mais controle sobre o service worker.
  • Você quer pré-armazenar em cache os arquivos.
  • Você precisa personalizar o roteamento e as estratégias.
  • Você quer usar seu service worker com outros recursos da plataforma (por exemplo, Push da Web).

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 da seguinte maneira:

// 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 para todos os recursos do webpack coletados pela sua configuração e as regras de armazenamento em cache do ambiente 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 da seguinte maneira:

// 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 cria um manifesto de pré-cache com base nos recursos de webpack coletados pela sua configuração e injeta-o no seu arquivo 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

Veja orientações sobre como usar os plug-ins no contexto de um build maior do webpack na seção Progressive Web Application da documentação do webpack.

Tipos

GenerateSW

Essa classe oferece suporte à criação de um novo arquivo de service worker 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 de 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 armazenadas em cache, além das 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 que será anexado aos nomes do cache. Isso é útil principalmente para desenvolvimento local em que vários sites podem ser veiculados da mesma origem de http://localhost:port.

  • pedaços

    string[] opcional

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

  • cleanupOutdatedCaches

    booleano opcional

    O valor padrão é: false.

    Define se o Workbox precisa tentar identificar e excluir pré-caches criados por versões mais antigas e incompatíveis.

  • clientsClaim

    booleano opcional

    O valor padrão é: false.

    Se o service worker precisa ou não começar a controlar os clientes existentes assim que ele for ativado.

  • directoryIndex

    string opcional

    Se uma solicitação de navegação para um URL com final / não corresponder a um URL pré-cache, esse valor será anexado ao URL e será verificado quanto a correspondência de pré-cache. Isso 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

    Será considerado que os recursos correspondentes têm controle de versões exclusivo pelo URL e estão isentos do impedimento de cache HTTP normal, que é feito ao preencher o pré-cache. Embora não seja obrigatório, é recomendável que, se o processo de build já inserir um valor [hash] em cada nome de arquivo, você forneça um RegExp para detectar isso, já que reduzirá a largura de banda consumida durante o pré-armazenamento em cache.

  • excluir

    (string | RegExp | função)[] opcional

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

  • excludeChunks

    string[] opcional

    Um ou mais nomes de bloco 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 correspondentes a uma das RegExp nessa matriz serão removidos antes que você procure uma correspondência de pré-cache. Isso é útil quando os usuários solicitam URLs que contêm, por exemplo, parâmetros de URL usados para rastrear a origem do tráfego. Se não for fornecido, o valor padrão será [/^utm_/, /^fbclid$/].

  • importScripts

    string[] opcional

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

  • importScriptsViaChunks

    string[] opcional

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

  • incluem

    (string | RegExp | função)[] opcional

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

  • inlineWorkboxRuntime

    booleano opcional

    O valor padrão é: false.

    Define se o código do ambiente de execução da biblioteca do 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 novamente do código da caixa de trabalho sempre que o service worker de nível superior for alterado.

  • 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 impede o armazenamento prévio em cache acidental de arquivos muito grandes que possam ter correspondido acidentalmente a um dos seus padrões.

  • modo

    string opcional

    Se definido como "produção", 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 poderá ser usado, por exemplo, para remover ou adicionar um prefixo de caminho de uma entrada de manifesto, se a configuração de hospedagem na Web não corresponder à configuração do sistema de arquivos local. Como alternativa com mais flexibilidade, você pode usar a opção manifestTransforms e fornecer uma função que modifique as entradas no manifesto usando qualquer lógica fornecida.

    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 de URLs que não são pré-armazenados em cache serão atendidas com o HTML no URL fornecido. É necessário transmitir o URL de um documento HTML listado no manifesto de pré-cache. Isso deve ser usado em um cenário de app de página única, em que você quer que todas as navegações usem um HTML do App Shell comum.

  • navigateFallbackAllowlist

    RegExp[] opcional

    Uma matriz opcional de expressões regulares que restringe a quais URLs o comportamento navigateFallback configurado se aplica. Isso é útil quando apenas um subconjunto de URLs do site precisa 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 complexos, ou os usuários poderão ter atrasos ao navegar no site.

  • navigateFallbackDenylist

    RegExp[] opcional

    Uma matriz opcional de expressões regulares que restringe a quais URLs o comportamento navigateFallback configurado se aplica. Isso é útil quando apenas um subconjunto de URLs do site precisa 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 complexos, ou os usuários poderão ter atrasos ao navegar no site.

  • navigationPreload

    booleano opcional

    O valor padrão é: false.

    Se o pré-carregamento de navegação será ativado ou não no service worker gerado. Quando definido como verdadeiro, você também precisa usar runtimeCaching para configurar uma estratégia de resposta apropriada que corresponda a solicitações de navegação e usar a resposta pré-carregada.

  • offlineGoogleAnalytics

    booleano | GoogleAnalyticsInitializeOptions opcional

    O valor padrão é: false.

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

  • runtimeCaching

    Tempo de execução em cache[] opcional

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

    Para todas as opções, consulte a documentação workbox-build.RuntimeCaching. O exemplo abaixo mostra uma configuração típica, com duas rotas de ambiente 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 for false, um listener message será adicionado, permitindo que as páginas de clientes acionem skipWaiting() chamando postMessage({type: 'SKIP_WAITING'}) em um service worker em espera.

  • mapa de origem

    booleano opcional

    O valor padrão é: true

    Define se um mapa de origem para os arquivos do service worker gerados será criado.

  • 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 é compatível com a compilação de um arquivo de service worker fornecido por swSrc e a injeção de uma lista de URLs e informações de revisão nesse service worker para pré-armazenamento em cache com base no pipeline de recursos do webpack.

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

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

// 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

  • construtor

    void

    Cria uma instância de InjectManifest.

    A função constructor tem esta aparência: 

    (config: WebpackInjectManifestOptions) => {...}

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

Propriedades

default

Tipo

objeto

Propriedades

  • GenerateSW

    consulta

  • InjectManifest

    consulta