build do arquivo de trabalho

O módulo workbox-build se integra a um processo de build baseado em nó e pode gerar um service worker inteiro ou apenas uma lista de recursos para pré-armazenar em cache que podem ser usados em um service worker.

Os dois modos que a maioria dos desenvolvedores usa são generateSW e injectManifest. As respostas às perguntas a seguir podem ajudar você a escolher a configuração e o modo corretos.

Qual modo usar

generateSW

O modo generateSW cria um arquivo de service worker para você, personalizado pelas opções de configuração, e o grava no disco.

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 modo injectManifest gera uma lista de URLs para pré-armazenar em cache e adiciona 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.

Modo generateSW

Você pode usar o modo generateSW em um script de build baseado em nó, utilizando as opções de configuração mais comuns, como:

// Inside of build.js:
const {generateSW} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while generating a service worker:',
      warnings.join('\n')
    );
  }

  console.log(`Generated a service worker, which will precache ${count} files, totaling ${size} bytes.`);
});

Isso vai gerar um service worker com a configuração de pré-armazenamento em cache para todos os arquivos coletados pela 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.

Modo injectManifest

Você pode usar o modo injectManifest em um script de build baseado em nó, utilizando as opções de configuração mais comuns, como:

// Inside of build.js:
const {injectManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
}).then(({count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while injecting the manifest:',
      warnings.join('\n')
    );
  }

  console.log(`Injected a manifest which will precache ${count} files, totaling ${size} bytes.`);
});

Isso cria um manifesto de pré-armazenamento em cache com base nos arquivos coletados pela configuração e o injetará no arquivo de service worker existente.

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

Outros modos

Esperamos que o generateSW ou o injectManifest atendam às necessidades da maioria dos desenvolvedores. No entanto, há um outro modo compatível com workbox-build que pode ser apropriado para determinados casos de uso.

Modo getManifest

Conceitualmente, ele é semelhante ao modo injectManifest, mas, em vez de adicionar o manifesto ao arquivo do service worker de origem, ele retorna a matriz de entradas do manifesto com informações sobre o número de entradas e o tamanho total.

Você pode usar o modo injectManifest em um script de build baseado em nó, utilizando as opções de configuração mais comuns, como:

// Inside of build.js:
const {getManifest} = require('workbox-build');

// These are some common options, and not all are required.
// Consult the docs for more info.
getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
}).then(({manifestEntries, count, size, warnings}) => {
  if (warnings.length > 0) {
    console.warn(
      'Warnings encountered while getting the manifest:',
      warnings.join('\n')
    );
  }

  // Do something with the manifestEntries, and potentially log count and size.
});

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

Tipos

BasePartial

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.

  • 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.

  • 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.

  • 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',
}

BuildResult

Tipo

Omitir<GetManifestResult"manifestEntries"
>&object

Propriedades

  • filePaths

    string[]

GeneratePartial

Propriedades

  • 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.

  • 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.

  • 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.

  • 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.

  • modo

    string opcional

    O valor padrão é: "production"

    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 process.env.NODE_ENV será usado e, caso contrário, ele voltará para 'production'.

  • 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

    boolean|GoogleAnalyticsInitializeOptions optional

    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

    RuntimeCaching[] 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.

GenerateSWOptions

Tipo

BasePartial&GlobPartial&GeneratePartial&RequiredSWDestPartial&OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial&GlobPartial&RequiredGlobDirectoryPartial

GetManifestResult

Propriedades

  • contagem

    number

  • manifestEntries

    ManifestEntry[]

  • tamanho

    number

  • avisos

    string[]

GlobPartial

Propriedades

  • globFollow

    booleano opcional

    O valor padrão é: true

    Determina se os links simbólicos são ou não seguidos ao gerar o manifesto de pré-cache. Para mais informações, consulte a definição de follow na documentação de glob.

  • globIgnores

    string[] opcional

    O valor padrão é: ["**\/node_modules\/**\/*"]

    Um conjunto de padrões que correspondem a arquivos a serem sempre excluídos ao gerar o manifesto de pré-cache. Para mais informações, consulte a definição de ignore na documentação de glob.

  • globPatterns

    string[] opcional

    O valor padrão é: ["**\/*.{js,css,html}"]

    Os arquivos que corresponderem a qualquer um desses padrões serão incluídos no manifesto de pré-cache. Para saber mais, consulte a glob.

  • globStrict

    booleano opcional

    O valor padrão é: true

    Se verdadeiro, um erro na leitura de um diretório ao gerar um manifesto de pré-cache fará com que a compilação falhe. Se for "false", o diretório problemático será ignorado. Para mais informações, consulte a definição de strict na documentação do glob.

  • templatedURLs

    objeto opcional

    Se um URL for renderizado com base em alguma lógica do lado do servidor, o conteúdo dele poderá depender de vários arquivos ou de algum outro valor de string exclusivo. As chaves nesse objeto são URLs renderizados pelo servidor. Se os valores forem uma matriz de strings, eles serão interpretados como padrões glob, e o conteúdo de todos os arquivos correspondentes aos padrões será usado para controlar as versões do URL de maneira exclusiva. Se usada com uma única string, ela será interpretada como informações de controle de versões exclusivas que você gerou para um determinado URL.

InjectManifestOptions

Tipo

BasePartial&GlobPartial&InjectPartial&RequiredSWDestPartial&RequiredGlobDirectoryPartial

InjectPartial

Propriedades

  • injectionPoint

    string opcional

    O valor padrão é: "self.__WB_MANIFEST"

    A string que será encontrada no arquivo swSrc. Depois de encontrado, ele será substituído pelo manifesto de pré-cache gerado.

  • swSrc

    string

    Caminho e nome do arquivo do service worker que será lido durante o processo de compilação em relação ao diretório de trabalho atual.

ManifestEntry

Propriedades

  • integridade

    string opcional

  • revisão

    string

  • url

    string

ManifestTransform()

workbox-build.ManifestTransform(
  manifestEntries: (ManifestEntry&object)[],
  compilation?: unknown,
)

Tipo

função

Parâmetros

  • manifestEntries

    (ManifestEntry&object)[]

    • tamanho

      number

  • compilação

    desconhecido opcional

Retorna

ManifestTransformResult

Propriedades

  • manifest

    (ManifestEntry&object)[]

    • tamanho

      number

  • avisos

    string[] opcional

OptionalGlobDirectoryPartial

Propriedades

  • globDirectory

    string opcional

    O diretório local a que você quer corresponder globPatterns. O caminho é relativo ao diretório atual.

RequiredGlobDirectoryPartial

Propriedades

  • globDirectory

    string

    O diretório local a que você quer corresponder globPatterns. O caminho é relativo ao diretório atual.

RequiredSWDestPartial

Propriedades

  • swDest

    string

    Caminho e nome de arquivo do arquivo do service worker que será criado pelo processo de compilação em relação ao diretório de trabalho atual. Ele precisa terminar em ".js".

RuntimeCaching

Propriedades

StrategyName

Tipo enumerado

"CacheFirst"

"CacheOnly"

"NetworkFirst"

WebpackGenerateSWOptions

Tipo

BasePartial&WebpackPartial&GeneratePartial&WebpackGenerateSWPartial

WebpackGenerateSWPartial

Propriedades

  • 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().

  • swDest

    string opcional

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

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

WebpackInjectManifestOptions

Tipo

BasePartial&WebpackPartial&InjectPartial&WebpackInjectManifestPartial

WebpackInjectManifestPartial

Propriedades

  • compileSrc

    booleano opcional

    O valor padrão é: true

    Quando true (padrão), o arquivo swSrc será compilado pelo webpack. Quando false, a compilação não ocorrerá, e webpackCompilationPlugins não poderá ser usado. Defina como false se quiser injetar o manifesto em, por exemplo, um arquivo JSON.

  • swDest

    string opcional

    O nome do recurso do arquivo do service worker que será criado por este plug-in. Se omitido, o nome será baseado no nome swSrc.

  • webpackCompilationPlugins

    qualquer[] opcional

    Plug-ins webpack opcionais que serão usados ao compilar o arquivo de entrada swSrc. Válida apenas se compileSrc for true.

WebpackPartial

Propriedades

  • 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.

  • excluir

    (string|RegExp|function)[] optional

    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.

  • include

    (string|RegExp|function)[] optional

    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.

  • 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.

Métodos

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
)

Isso copia um conjunto de bibliotecas de ambiente de execução usadas pelo Workbox em um diretório local, que precisa ser implantado com o arquivo do service worker.

Como alternativa à implantação dessas cópias locais, você pode usar o Workbox do URL da CDN oficial.

Esse método é exposto para benefício de desenvolvedores que usam workbox-build.injectManifest, que preferem não usar as cópias da CDN do Workbox. Os desenvolvedores que usam workbox-build.generateSW não precisam chamar esse método explicitamente.

Parâmetros

  • destDirectory

    string

    O caminho para o diretório pai em que o novo diretório de bibliotecas será criado.

Retorna

  • Promessa<string>

    O nome do diretório recém-criado.

generateSW()

workbox-build.generateSW(
  config: GenerateSWOptions,
)

Esse método cria uma lista de URLs para pré-armazenar em cache, conhecido como "manifesto de pré-cache", com base nas opções fornecidas.

Ele também aceita outras opções que configuram o comportamento do service worker, como qualquer regra runtimeCaching que ele precisa usar.

Com base no manifesto de pré-cache e na configuração extra, ele grava um arquivo de service worker pronto para uso no disco em swDest.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await generateSW({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  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: ...,
  swDest: '...',
});

Parâmetros

Retorna

getManifest()

workbox-build.getManifest(
  config: GetManifestOptions,
)

Esse método retorna uma lista de URLs para pré-armazenar em cache, o que é chamado de "manifesto de pré-cache", com detalhes sobre o número de entradas e o tamanho delas, com base nas opções fornecidas.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, manifestEntries, size, warnings} = await getManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
});

Parâmetros

Retorna

getModuleURL()

workbox-build.getModuleURL(
  moduleName: string,
  buildType: BuildType,
)

Parâmetros

  • moduleName

    string

  • buildType

    BuildType

Retorna

  • string

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
)

Esse método cria uma lista de URLs para pré-armazenar em cache, conhecido como "manifesto de pré-cache", com base nas opções fornecidas.

O manifesto é injetado no arquivo swSrc, e a string de marcador de posição injectionPoint determina em que local do arquivo o manifesto será colocado.

O arquivo final do service worker, com o manifesto injetado, é gravado no disco em swDest.

Esse método não vai compilar nem agrupar o arquivo swSrc. Ele apenas processa a injeção do manifesto.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
const {count, size, warnings} = await injectManifest({
  dontCacheBustURLsMatching: [new RegExp('...')],
  globDirectory: '...',
  globPatterns: ['...', '...'],
  maximumFileSizeToCacheInBytes: ...,
  swDest: '...',
  swSrc: '...',
});

Parâmetros

Retorna