build do arquivo de trabalho

O módulo workbox-build é integrado a um processo de build baseado em nó e pode gerar um worker de serviço inteiro ou apenas uma lista de recursos para pré-cachear que podem ser usados em um worker de serviço existente.

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

Qual modo usar

generateSW

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

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 modo injectManifest vai gerar uma lista de URLs para pré-cachear e adicionar esse manifesto de pré-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 de serviço.
  • Você quer pré-cachear arquivos.
  • Você precisa personalizar o roteamento e as estratégias.
  • Você quer usar o 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.

Modo generateSW

É possível usar o modo generateSW em um script de build baseado em nó usando as opções de configuração mais comuns, como esta:

// 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 de todos os arquivos escolhidos 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

É possível usar o modo injectManifest em um script de build baseado em nó usando as opções de configuração mais comuns, como esta:

// 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 vai criar um manifesto de pré-cache com base nos arquivos coletados pela configuração e injetá-lo no arquivo de worker de serviço atual.

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

Outros modos

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

Modo getManifest

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

É possível usar o modo injectManifest em um script de build baseado em nó usando as opções de configuração mais comuns, como esta:

// 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 pré-armazenadas em cache, além de entradas geradas como parte da configuração do build.

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

  • 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 pré-armazenados em cache. Isso evita que você pré-cacheie acidentalmente arquivos muito grandes que podem ter sido combinados acidentalmente com um dos seus padrões.

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

BuildResult

Tipo

Omit<GetManifestResult"manifestEntries"
> & object

Propriedades

  • filePaths

    string[]

GeneratePartial

Propriedades

  • babelPresetEnvTargets

    string[] opcional

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

    Os alvos a serem transmitidos para babel-preset-env ao transpiltar o pacote de worker de serviço.

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

  • 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 em cache, esse valor será anexado ao URL e será verificado para uma correspondência de pré-cache. Ele precisa ser definido como o que o servidor da Web está usando para o índice de diretório.

  • disableDevLogs

    booleano opcional

    O valor padrão é false.

  • ignoreURLParametersMatching

    RegExp[] opcional

    Todos os nomes de parâmetros de pesquisa que correspondem a um dos RegExps neste array 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 deixar o Workbox criar seu arquivo de service worker de nível superior, mas quer incluir algum código adicional, como um listener de eventos push.

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

  • modo

    string opcional

    O valor padrão é: "production"

    Se definido como "production", um pacote de worker de serviço 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. Caso contrário, o valor padrão será 'production'.

  • 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. É necessário 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 os URLs aos quais 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: esses RegExps podem ser avaliados em todos os URLs 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 os URLs aos quais 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: esses RegExps podem ser avaliados em todos os URLs 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

    boolean | GoogleAnalyticsInitializeOptions optional

    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 o 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. Elas são traduzidas para chamadas workbox-routing.registerRoute usando a configuração de correspondência e gerenciador definida.

    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.

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 seguidos ou não ao gerar o manifesto do pré-cache. Para mais informações, consulte a definição de follow na documentação do glob.

  • globIgnores

    string[] opcional

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

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

  • globPatterns

    string[] opcional

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

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

  • globStrict

    booleano opcional

    O valor padrão é true.

    Se definido como "true", um erro ao ler um diretório ao gerar um manifesto de pré-cache fará com que o build falhe. Se for falso, 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 neste 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 que corresponderem aos padrões será usado para criar uma versão exclusiva do URL. Se usado com uma única string, ele será interpretado como informações de controle de versão exclusivo geradas 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 a ser encontrada no arquivo swSrc. Depois de encontrado, ele será substituído pelo manifesto de pré-cache gerado.

  • swSrc

    string

    O caminho e o nome do arquivo do worker de serviço que serão lidos durante o processo de build, 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

  • manifesto

    (ManifestEntry & object)[]

    • tamanho

      number

  • avisos

    string[] opcional

OptionalGlobDirectoryPartial

Propriedades

  • globDirectory

    string opcional

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

RequiredGlobDirectoryPartial

Propriedades

  • globDirectory

    string

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

RequiredSWDestPartial

Propriedades

  • swDest

    string

    O caminho e o nome do arquivo do worker de serviço que será criado pelo processo de build, em relação ao diretório de trabalho atual. Ele precisa terminar em '.js'.

RuntimeCaching

Propriedades

StrategyName

Enumeração

"CacheFirst"

"CacheOnly"

"NetworkFirst"

"NetworkOnly"

"StaleWhileRevalidate"

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 worker de serviço 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 ocorre (e webpackCompilationPlugins não pode 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 worker do serviço que será criado por este plug-in. Se omitido, o nome será baseado no nome swSrc.

  • webpackCompilationPlugins

    any[] opcional

    Plugins webpack opcionais que serão usados ao compilar o arquivo de entrada swSrc. Válido apenas se compileSrc for true.

WebpackPartial

Propriedades

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

  • 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 fragmentos cujos arquivos de saída correspondentes precisam ser excluídos do manifesto de pré-cache.

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

  • modo

    string opcional

    Se definido como "production", um pacote de worker de serviço 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 execução usadas pelo Workbox para 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 pelo URL oficial da CDN.

Esse método é exposto para beneficiar os desenvolvedores que usam workbox-build.injectManifest e preferem não usar as cópias do 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

  • Promise<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é-cachear, chamada de "manifesto de pré-cache", com base nas opções fornecidas.

Ele também recebe 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 adicional, ele grava um arquivo de worker de serviço 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é-cache, chamada de "manifesto de pré-cache", além de 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é-cachear, chamada de "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 onde o manifesto precisa ser colocado no arquivo.

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

Esse método não vai compilar nem agrupar seu 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