Como transformar seu site em um progressive web app
Como transformar seu site em um PWA (código testado) | We.Inc
Deixe qualquer site instalável e pronto para funcionar offline: um gerador de manifest, um service worker testado, um botão de instalar, os limites do iPhone e a configuração em Vite ou Next.js.
Como transformar seu site em um progressive web app
Para transformar um site em um progressive web app, sirva-o por HTTPS, adicione um manifest.webmanifest com nome, start_url, modo de exibição e ícones de 192 e 512 pixels, vincule-o em todas as páginas e registre um service worker que guarde os arquivos em cache para uso offline. Os navegadores Chromium passam a oferecer a instalação; quem usa Safari adiciona pelo menu Compartilhar.
As três partes de um PWA
Parte
O que faz
Nome, ícones, cores e como o app abre
Service worker (sw.js)
Guarda arquivos em cache para que as páginas carreguem offline
HTTPS
Obrigatório para service workers e para a instalação
Preencha o formulário para obter um manifest e as tags do head para colar, depois copie o service worker e o script de instalação. O worker desta página foi executado em um navegador real com a rede cortada antes de publicarmos.
Crie ícones de 192 e 512 pixels, mais uma versão maskable com o logo dentro dos 80 por cento centrais.
Gere o manifest com o formulário, salve-o como manifest.webmanifest na raiz do site e cole as tags do head em todas as páginas.
Salve sw.js, offline.html e o script de registro, e liste seus arquivos principais em PRECACHE.
Abra o Chrome DevTools, painel Application: confira Manifest para ver problemas de instalação e Service workers para ver o worker em execução. Marque Offline e recarregue para testar.
Quando mudar arquivos em cache, aumente VERSION para que os visitantes que voltam recebam os novos.
Sirva o sw.js a partir da raiz do site. Um worker só controla páginas na própria pasta ou abaixo dela.
Não coloque o próprio sw.js em cache com cabeçalhos HTTP de cache longos; os navegadores o verificam em busca de atualizações.
Mantenha a lista de precache curta. Tudo o que estiver nela é baixado na primeira visita.
No iPhone, explique às pessoas como instalar: Compartilhar e depois Adicionar à Tela de Início. Não existe um aviso para disparar.
Teste o modo offline parando também o seu servidor local, além de usar a caixa Offline, para que as requisições do próprio worker também falhem.
Perguntas frequentes
Um PWA precisa de service worker para ser instalável?
No Chrome atual, não: um manifest válido, HTTPS e algum engajamento do usuário bastam para a opção de instalar. Ainda assim você quer um worker, porque sem ele o app instalado mostra a página de erro do navegador quando está offline.
PWAs funcionam no iPhone?
Sim, com limites. Quem usa Safari instala pelo menu Compartilhar, não existe o evento de aviso de instalação e as notificações push só funcionam para um site adicionado à Tela de Início no iOS 16.4 ou mais recente. O cache offline funciona.
Por que meu botão de instalar nunca aparece?
beforeinstallprompt só dispara em navegadores Chromium, só quando os critérios de instalação são atendidos e não quando o app já está instalado. Veja o motivo na seção Manifest do painel Application do DevTools.
Como verifico um PWA agora que o Lighthouse não tem mais nota de PWA?
O Lighthouse 12 removeu a categoria PWA. Use o painel Application do Chrome DevTools: a visão Manifest lista erros de instalabilidade e problemas de ícone, e a visão Service workers mostra o registro, as atualizações e um botão Offline.
Como atualizo um PWA depois de um lançamento?
Mude o VERSION do cache no sw.js. O navegador percebe o worker alterado, instala-o, e a etapa activate remove os caches antigos. Com skipWaiting e clients.claim, o novo worker assume no próximo carregamento.
Cache-first ou network-first
Cache-first responde a partir do cache e só vai à rede para o que ainda não guardou. É rápido e certo para arquivos cujo conteúdo nunca muda com o mesmo nome, como scripts com hash, fontes e ícones.
Network-first pergunta ao servidor e só usa o cache quando isso falha. Combina com páginas HTML, em que mostrar uma cópia antiga depois de uma atualização confundiria as pessoas. O worker acima usa os dois: network-first para carregamentos de página, cache-first para todo o resto.
Erros comuns
Registrar o worker a partir de um caminho de subpasta como /js/sw.js, o que o limita às páginas em /js/.
Esquecer de mudar VERSION, e os visitantes que voltam ficam com CSS e scripts antigos por semanas.
Guardar em cache respostas de outros sites ou respostas de erro. O worker acima ignora requisições de outra origem e só guarda respostas de assets bem-sucedidas.
Testar só no Chrome. Abra o site em um iPhone para ver o que quem usa Safari realmente recebe.
O que você ganha, e os limites no iPhone
Instalar dá ao seu site um ícone próprio e uma janela sem a barra de endereço. Um service worker adiciona páginas offline. O push precisa dos dois, e a Apple só o permite para sites que o usuário adicionou à Tela de Início.
O que um PWA consegue fazer, por plataforma
Recurso
Chrome / Edge (desktop, Android)
Safari no iPhone e no iPad
Firefox
Instalar na tela inicial ou na área de trabalho
Sim, com aviso de instalação
Sim, manualmente: Compartilhar e depois Adicionar à Tela de Início
Android: sim. Desktop: limitado, confira sua versão
Botão de instalar personalizado (beforeinstallprompt)
Sim
Não
Não
Offline com service worker
Sim
Sim
Sim
Notificações web push
Sim
Só para um site adicionado à Tela de Início, iOS 16.4 ou mais recente
Sim
Armazenamento que persiste
Sim, pode ser removido quando falta espaço
Em abas do Safari, o armazenamento gravado por script pode ser apagado após 7 dias de uso do navegador sem visita; apps da Tela de Início têm a própria contagem
Sim, pode ser removido quando falta espaço
Sincronização em segundo plano
Sim
Não
Não
Um service worker que funciona
Três arquivos fazem um site funcionar offline: o worker, uma página de fallback e algumas linhas para registrá-lo. Rodamos exatamente estes arquivos em localhost no Chromium: o worker foi instalado, o cache foi preenchido e, com o servidor parado, a página inicial carregou do cache enquanto uma página nunca visitada mostrou o offline.html.
sw.js: um service worker mínimo que funciona offline
As páginas tentam a rede primeiro para que as pessoas vejam conteúdo atualizado, depois recorrem a uma cópia em cache e por fim ao offline.html. Arquivos como CSS, scripts e ícones vêm primeiro do cache. Mudar VERSION faz a próxima etapa activate apagar os caches antigos.
offline.html: a página de fallback
Deixe-a autossuficiente: estilos inline e nenhum arquivo externo, porque nada mais pode estar acessível quando ela aparecer.
Um botão de instalar
app.js: registre o worker e mostre um botão de instalar
O evento beforeinstallprompt só dispara em navegadores Chromium (Chrome, Edge, Samsung Internet, Opera). Safari e Firefox nunca o enviam, então o botão fica oculto neles e as pessoas usam o menu do próprio navegador.
Critérios de instalação hoje
O Chrome não exige mais um service worker para oferecer a instalação; ele verifica o manifest e os itens abaixo. O Lighthouse 12 removeu a categoria PWA, então verifique a instalabilidade no Chrome DevTools: painel Application, depois Manifest, que lista qualquer problema em Installability.
Requisitos de instalação do Chrome
Requisito
Detalhe
HTTPS
Servido com segurança. localhost conta como seguro para testes.
Nome no manifest
name ou short_name
Ícones no manifest
Pelo menos um ícone de 192 px e um de 512 px
Presente no manifest
fullscreen, standalone, minimal-ui ou window-controls-overlay
Ausente ou false
Engajamento
O visitante clicou ou tocou na página pelo menos uma vez e passou algum tempo nela
Configuração em Vite e Next.js
Vite: vite-plugin-pwa
Instale com npm i -D vite-plugin-pwa. O plugin escreve o manifest e gera um service worker Workbox no build, então você não escreve o sw.js à mão. Coloque os ícones em public/.
Next.js App Router: app/manifest.ts
O Next.js serve este arquivo em /manifest.webmanifest e adiciona a tag link para você. Para suporte offline, coloque o sw.js acima em public/ e registre-o a partir de um pequeno client component.
Next.js: registre public/sw.js a partir de um client component
Renderize isto uma vez em app/layout.tsx. Pule o registro em desenvolvimento para que um build em cache não esconda suas edições.
Nome do app
Nome curto (abaixo do ícone)
URL inicial
Pasta dos ícones
Cor do tema
Cor de fundo
Copiar
Gerador de manifest
Exibição
Incluir um ícone maskable
Salve seus ícones como icon-192.png e icon-512.png (e icon-512-maskable.png) na pasta dos ícones.