workbox-cli

A interface de linha de comando Workbox (contida no pacote workbox-cli) consiste em um programa Node.js chamado "workbox" que pode ser executado em um ambiente de linha de comando compatível com UNIX, Windows e macOS. Internamente, o workbox-cli une o módulo workbox-build e fornece uma maneira fácil de integrar o Workbox a um processo de compilação de linha de comando, com configurações flexíveis.

Instalar a CLI

Para instalar a CLI com o Node, execute o seguinte comando no terminal:

npm install workbox-cli --global

Modos da CLI

A CLI tem quatro modos diferentes:

  • wizard: um guia explicativo para configurar o Workbox para seu projeto.
  • generateSW: gera um service worker completo para você.
  • injectManifest: injeta os recursos para pré-armazenar em cache no projeto.
  • copyLibraries: copia as bibliotecas da Workbox para um diretório.

wizard

O assistente do Workbox faz uma série de perguntas sobre a configuração do diretório local e quais arquivos você quer armazenar em cache. Suas respostas são usadas para gerar um arquivo de configuração que pode ser usado quando executado no modo generateSW.

A maioria dos desenvolvedores só precisa executar o assistente de caixa de trabalho uma vez, e você pode personalizar manualmente o arquivo de configuração inicial gerado usando qualquer uma das opções de configuração do build com suporte.

Para iniciar o assistente, execute:

npx workbox-cli wizard

Captura de tela do assistente da CLI do Workbox

generateSW

É possível usar a CLI do Workbox para gerar um service worker completo usando um arquivo de configuração, como o arquivo gerado pelo assistente.

Basta executar o seguinte comando:

npx workbox-cli generateSW path/to/config.js

Os desenvolvedores que estão satisfeitos com os recursos integrados de pré-armazenamento em cache e de tempo de execução do Workbox e que não precisam personalizar o comportamento do service worker precisam usar o modo generateSW.

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

Para desenvolvedores que querem mais controle sobre o arquivo do service worker final, é possível usar o modo injectManifest. Esse modo pressupõe que você tenha um arquivo do service worker (com o local especificado em config.js).

Quando workbox injectManifest é executado, ele procura uma string específica (precacheAndRoute(self.__WB_MANIFEST) por padrão) no arquivo do service worker de origem. Ele substitui a matriz vazia por uma lista de URLs para pré-armazenar em cache e grava o arquivo do service worker no local de destino, com base nas opções de configuração em config.js. O restante do código no service worker de origem não é alterado.

Use o Workbox nesse modo:

npx workbox-cli injectManifest path/to/config.js

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.

copyLibraries

Esse modo é útil se você quiser usar injectManifest e usar os arquivos da biblioteca do Workbox hospedados na sua própria origem, em vez de usar a CDN.

Você só precisa executá-lo com um caminho para gravar os arquivos em:

npx workbox-cli copyLibraries third_party/workbox/

Integração do processo de build

Por que o Workbox precisa se integrar ao meu processo de compilação?

O projeto Workbox contém várias bibliotecas que trabalham juntas para potencializar o service worker do seu app da Web. Para usar essas bibliotecas de forma eficaz, o Workbox precisa estar integrado ao processo de build do app da Web. Isso garante que o service worker seja capaz de pré-armazenar em cache com eficiência todo o conteúdo essencial do app da Web e manter esse conteúdo atualizado.

O workbox-cli é a escolha certa para meu processo de build?

Se você já tiver um processo de build totalmente baseado em scripts npm, o workbox-cli será uma boa escolha.

Se você estiver usando o webpack como ferramenta de build, usar o workbox-webback-plugin é uma opção melhor.

Se você estiver usando atualmente Gulp, Grunt ou alguma outra ferramenta de build baseada em Node.js, integrar workbox-build ao seu script de build é uma opção melhor.

Se você não tiver um processo de build, crie um antes de usar o Workbox para pré-armazenar em cache qualquer um dos seus recursos. Tentar se lembrar de executar workbox-cli manualmente pode ser propenso a erros, e esquecer de executá-lo pode levar à exibição de conteúdo obsoleto aos visitantes recorrentes.

Configuração

Depois de instalar workbox-cli como uma dependência de desenvolvimento para seu projeto local, adicione a chamada a workbox no final do script npm do processo de build atual:

No package.json:

{
  "scripts": {
    "build": "my-build-script && workbox <mode> <path/to/config.js>"
  }
}

Substitua <mode> por generateSW ou injectManifest (dependendo do caso de uso) e <path/to/config.js> pelo caminho para as opções de configuração. Sua configuração pode ter sido criada automaticamente por workbox wizard ou ajustada manualmente.

Configuração

Opções usadas pelo app generateSW

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

Opções usadas pelo app injectManifest

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