Conheça os recursos do Workbox

O Workbox é flexível o suficiente para acomodar praticamente o processo de compilação de qualquer projeto. Isso significa que há mais de uma maneira de usar o Workbox, permitindo que você escolha a integração certa para seu projeto. Independente de como você se integra ao Workbox, as diversas ferramentas oferecem uma API semelhante.

generateSW x injectManifest

Você vai usar um dos dois métodos principais das ferramentas de build do Workbox: generateSW ou injectManifest. Qual delas você deve usar depende de quanta flexibilidade você precisa. O generateSW prioriza a facilidade de uso e a simplicidade em detrimento da flexibilidade. Assim, você pode declarar um conjunto de opções de configuração e, em troca, ter um service worker totalmente funcional.

injectManifest favorece uma maior flexibilidade em detrimento de alguma simplicidade, já que você vai acabar escrevendo o código para o service worker, com injectManifest fornecendo um manifesto de pré-cache que pode ser usado pelos métodos de pré-armazenamento em cache do Workbox.

Quando usar generateSW

Use generateSW se:

  • Você quer pré-armazenar em cache arquivos associados ao seu processo de build, incluindo arquivos com URLs com hashes que você talvez não conheça com antecedência.
  • Você tem necessidades simples de armazenamento em cache no ambiente de execução que podem ser configuradas usando as opções do generateSW.

Quando não usar generateSW

Por outro lado, não use generateSW se:

  • Você quer usar outros recursos do service worker (como o envio por push da Web).
  • Você precisa de mais flexibilidade para importar scripts adicionais ou usar módulos específicos do Workbox para ajustar o service worker às necessidades do seu aplicativo.

Quando usar injectManifest

Use injectManifest se:

  • Você quer pré-armazenar em cache os arquivos, mas criar seu próprio service worker.
  • Você tem necessidades complexas de roteamento ou armazenamento em cache que não podem ser expressas pelas opções de configuração do generateSW.
  • Você quer usar outras APIs no service worker (como push da Web).

injectManifest é diferente de generateSW porque exige que você especifique um arquivo de service worker de origem. Nesse fluxo de trabalho, o arquivo do service worker de origem precisa ter uma string self.__WB_MANIFEST especial para que o injectManifest possa substituí-lo pelo manifesto de pré-cache.

Quando não usar injectManifest

Não use injectManifest se:

  • Não é recomendável usar o pré-armazenamento em cache no service worker.
  • nossos requisitos de service worker são simples o suficiente para serem atendidos pelo que o generateSW e as opções de configuração podem oferecer.
  • Você prioriza a facilidade de uso em vez da flexibilidade.

Usar as ferramentas de build do Workbox

Se você está procurando uma maneira independente de framework de usar o Workbox no seu processo de compilação, há três opções:

  1. workbox-cli
  2. workbox-build. ferramenta de linha de comando.
  3. Usando um bundler (como workbox-webpack-plugin).

Cada uma dessas ferramentas de build oferece os modos generateSW e injectManifest, com um conjunto semelhante de opções. Todas essas opções são boas opções quando você não quer vincular seu service worker com a tecnologia do Workbox a um framework específico. Para saber qual é a melhor opção, vamos analisar rapidamente cada uma.

workbox-cli

Se você está procurando a menor barreira possível para entrar no Workbox, a CLI é para você:

npm install workbox-cli --save-dev

Para começar a usar a CLI, execute o assistente com npx workbox wizard. O assistente fará algumas perguntas, e as respostas serão usadas para configurar um projeto com um arquivo workbox-config.js que pode ser personalizado para atender às suas necessidades. A aparência será semelhante a esta:

// A config for `generateSW`
export default {
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{css,woff2,png,svg,jpg,js}'
  ],
  swDest: 'dist/sw.js'
};

Depois que o arquivo de configuração for criado, a CLI poderá executar os métodos generateSW ou injectManifest. O texto de ajuda da CLI tem mais informações e exemplos de uso.

workbox-build

O workbox-cli é um wrapper em torno do módulo workbox-build, e uma alternativa é usar workbox-build diretamente. Ao usar workbox-build, em vez de especificar opções usando um arquivo workbox-config.js, você usará os métodos generateSW ou injectManifest diretamente como parte de um script Node, transmitindo um conjunto semelhante de opções:

// build-sw.mjs
import {generateSW} from 'workbox-build';

generateSW({
  globDirectory: 'dist/',
  globPatterns: [
    '**/*.{css,woff2,png,svg,jpg,js}'
  ],
  swDest: 'dist/sw.js'
});

No exemplo acima, workbox-build gravará o service worker gerado no diretório dist quando o comando node build-sw.mjs for executado.

Como usar um bundler

Vários bundlers têm plug-ins próprios do Workbox, mas o único bundler compatível oficialmente pela equipe do Workbox é o webpack, via workbox-webpack-plugin. Assim como workbox-cli e workbox-build, workbox-webpack-plugin vai executar os métodos generateSW ou injectManifest, mas o plug-in vai colocar esses nomes de método em maiúscula como GenerateSW ou InjectManifest. Caso contrário, o uso é semelhante a workbox-build:

// webpack.config.js
import {GenerateSW} from 'workbox-webpack-plugin';

export default {
  // Other webpack config options omitted for brevity...
  plugins: [
    new GenerateSW({
      swDest: './dist/sw.js'
    })
  ]
};

As opções transmitidas para GenerateSW ou InjectManifest não são iguais a generateSW ou injectManifest, mas há uma sobreposição significativa. Em particular, você não precisa (nem pode) especificar uma opção globDirectory para GenerateSW, pois o webpack já sabe onde seus recursos de produção estão agrupados.

Usar um framework

Tudo que abordamos até aqui trata do uso do Workbox, independentemente das preferências de framework da pessoa. No entanto, é possível usar o Workbox em um framework específico caso isso facilite o desenvolvimento. Por exemplo, create-react-app é enviado com o Workbox por padrão. Diferentes integrações de framework com o Workbox são abordadas posteriormente em um artigo posterior.

Vale notar que essas integrações do Workbox específicas de cada framework podem restringir sua capacidade de configurar o Workbox da maneira que você quiser. Em casos como esses, sempre é possível usar os métodos discutidos aqui.

E se eu não tiver um processo de criação?

Este documento supõe que seu projeto tem um processo de compilação, mas, de fato, seu projeto pode não. Se isso descreve sua situação, ainda é possível usar o Workbox com o módulo workbox-sw. Com o workbox-sw, é possível carregar o ambiente de execução do Workbox por uma CDN ou localmente e compor seu próprio service worker.

Conclusão

A flexibilidade do Workbox garante que ele possa ser usado em praticamente qualquer projeto, independente das preferências do framework ou do conjunto de ferramentas. Todos esses caminhos permitem que você realize o armazenamento em cache antes e durante a execução usando alguns métodos, ao mesmo tempo em que proporciona maior flexibilidade para criar service workers com recursos mais avançados quando necessário.