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