build do arquivo de trabalho

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

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 o modo e a configuração certos para usar.

Qual modo usar

generateSW

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

Quando usar generateSW

  • Você quer pré-armazenar arquivos em cache.
  • Você tem necessidades simples de armazenamento em cache de tempo 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 cache personalizadas.

injectManifest

O modo 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 será deixado como está.

Quando usar injectManifest

  • Você quer mais controle sobre o service worker.
  • Você quer pré-armazenar arquivos em cache.
  • É necessário 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 a maneira mais fácil de adicionar um service worker ao seu site.

Modo generateSW

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

// 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 configuração de pré-cache para todos os arquivos selecionados pela sua configuração e as regras de cache de tempo 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ós, usando as opções de configuração mais comuns, assim:

// 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 service worker 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 do service worker de origem, ele retorna a matriz de entradas de 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ós, usando as opções de configuração mais comuns, assim:

// 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 todas as entradas geradas como parte da configuração de build.

  • dontCacheBustURLsMatching

    RegExp opcional

    Os recursos que corresponderem a isso serão considerados com versão exclusiva pelo URL e isentos da limpeza normal do cache HTTP feita 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 uma RegExp que detecte isso, já que ela reduz a largura de banda consumida durante o pré-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 optional

    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 o pré-armazenamento em cache inadvertido de arquivos muito grandes que podem 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 pode ser usado para, por exemplo, 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 uma alternativa mais flexível, você pode usar a opção manifestTransforms e fornecer uma função que modifique as entradas no manifesto usando a 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 targets a serem transmitidos para babel-preset-env ao transcompilar o pacote do service worker.

  • cacheId

    string opcional

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

  • cleanupOutdatedCaches

    booleano opcional

    O valor padrão é false.

    Se o Workbox deve 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 deve começar a controlar todos os clientes atuais 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 verificado para uma correspondência de pré-armazenamento em cache. Isso precisa ser definido como o que seu 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 corresponderem a uma das RegExp neste array serão removidos antes de procurar uma correspondência de pré-cache. Isso é útil se os usuários solicitarem URLs que contenham, 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() no arquivo de 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 algum código adicional, como um listener de eventos push.

  • inlineWorkboxRuntime

    booleano opcional

    O valor padrão é false.

    Se o código de tempo de execução da biblioteca Workbox deve ser incluído no service worker de nível superior ou dividido em um arquivo separado que precisa ser implantado junto com o service worker. Manter o tempo de execução separado significa que os usuários não precisam baixar novamente o código do Workbox sempre que o service worker de nível superior muda.

  • modo

    string opcional

    O valor padrão é: "production"

    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 process.env.NODE_ENV será usado e, se isso não for possível, ele vai voltar para 'production'.

  • navigateFallback

    string opcional

    O valor padrão é: null

    Se especificado, todos os pedidos de navegação para URLs que não foram pré-armazenados em cache serão atendidos com o HTML no URL fornecido. Você precisa transmitir o URL de um documento HTML listado no manifesto de pré-cache. Isso deve ser usado em um cenário de aplicativo 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 a que o comportamento navigateFallback configurado se aplica. Isso é útil se apenas um subconjunto dos URLs do seu site deve ser tratado como parte de um aplicativo de página única. Se navigateFallbackDenylist e navigateFallbackAllowlist forem configurados, a lista de bloqueio terá precedência.

    Observação: essas expressões regulares podem ser avaliadas em relação a todos os URLs de destino durante uma navegação. Evite usar expressões regulares complexas, caso contrário, os usuários poderão ter atrasos ao navegar no seu site.

  • navigateFallbackDenylist

    RegExp[] opcional

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

    Observação: essas expressões regulares podem ser avaliadas em relação a todos os URLs de destino durante uma navegação. Evite usar expressões regulares complexas, caso contrário, os usuários poderão ter atrasos ao navegar no seu site.

  • navigationPreload

    booleano opcional

    O valor padrão é false.

    Se a pré-carga de navegação será ativada ou não no service worker gerado. Quando definido como "true", você também precisa 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. Quando true, a chamada para initialize() de workbox-google-analytics será adicionada ao service worker gerado. Quando definido como um 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 service worker, é possível especificar uma ou mais configurações de cache de tempo de execução. Em seguida, eles são traduzidos para chamadas workbox-routing.registerRoute usando a configuração de correspondência e manipulador 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 tempo de execução definidas:

  • skipWaiting

    booleano opcional

    O valor padrão é false.

    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 service worker em espera.

  • sourcemap

    booleano opcional

    O valor padrão é true.

    Se um mapa de origem será criado para os arquivos de service worker gerados.

GenerateSWOptions

Tipo

BasePartial & GlobPartial & GeneratePartial & RequiredSWDestPartial & OptionalGlobDirectoryPartial

GetManifestOptions

Tipo

BasePartial & GlobPartial & RequiredGlobDirectoryPartial

GetManifestResult

Propriedades

  • contagem

    número

  • manifestEntries

    ManifestEntry[]

  • tamanho

    número

  • avisos

    string[]

GlobPartial

Propriedades

  • globFollow

    booleano opcional

    O valor padrão é true.

    Determina se os symlinks são seguidos ao gerar o manifesto de 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 correspondentes 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 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 guia de 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 que corresponderem aos padrões será usado para versionar o URL de maneira exclusiva. Se usado com uma única string, ele será interpretado como informações de controle de versão exclusivas 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 service worker que será lido 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,
): Promise<ManifestTransformResult> | ManifestTransformResult

Tipo

função

Parâmetros

  • manifestEntries

    (ManifestEntry & object)[]

    • tamanho

      número

  • compilação

    unknown optional

Retorna

ManifestTransformResult

Propriedades

  • manifesto

    (ManifestEntry & object)[]

    • tamanho

      número

  • avisos

    string[] opcional

OptionalGlobDirectoryPartial

Propriedades

  • globDirectory

    string opcional

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

RequiredGlobDirectoryPartial

Propriedades

  • globDirectory

    string

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

RequiredSWDestPartial

Propriedades

  • swDest

    string

    O caminho e o nome do arquivo do service worker que será criado pelo processo de build, relativo 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 partes 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 de 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 (o padrão), o arquivo swSrc é compilado pelo webpack. Quando false, a compilação não vai ocorrer, e webpackCompilationPlugins não poderá ser usado. Defina como false se quiser injetar o manifesto em um arquivo JSON, por exemplo.

  • swDest

    string opcional

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

  • webpackCompilationPlugins

    any[] optional

    Plug-ins 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 partes 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 da opção padrão exclude do webpack. Se não for fornecido, o valor padrão será [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] opcional

    Um ou mais nomes de partes 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 da opção padrão include do webpack.

  • 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 de mode configurado na compilação de webpack atual será usado.

Métodos

copyWorkboxLibraries()

workbox-build.copyWorkboxLibraries(
  destDirectory: string,
): Promise<string>

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

Como alternativa à implantação dessas cópias locais, use o Workbox no URL oficial da CDN.

Esse método é exposto para beneficiar desenvolvedores que usam workbox-build.injectManifest e 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 principal 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,
): Promise<BuildResult>

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

Ele também usa outras opções que configuram o comportamento do service worker, como as regras runtimeCaching que ele deve usar.

Com base no manifesto de pré-cache e na configuração adicional, 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,
): Promise<GetManifestResult>

Esse método retorna uma lista de URLs para pré-armazenar em cache, chamada de "manifesto de pré-armazenamento em 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,
): string

Parâmetros

  • moduleName

    string

  • buildType

    BuildType

Retorna

  • string

injectManifest()

workbox-build.injectManifest(
  config: InjectManifestOptions,
): Promise<BuildResult>

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

O manifesto é injetado no arquivo swSrc, e a string de marcador de posição injectionPoint determina onde no arquivo o manifesto deve ficar.

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

Esse método não compila nem agrupa 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