Gerador de PWA manifest.json

manifest.json: o arquivo que transforma um site em PWA instalável

O Web App Manifest é um arquivo JSON padronizado pelo W3C que descreve para navegadores e sistemas operacionais como seu site deve se comportar quando instalado como aplicativo. É o ingrediente que transforma um site comum em Progressive Web App — ícone na tela inicial, splash screen no boot, janela sem barra de URL e capacidade de registrar handlers de compartilhamento, tipos de arquivo e shortcuts do SO. Sem manifest, o Chrome se recusa a exibir o prompt de instalação, e o iOS só oferece um suporte limitado de "Adicionar à Tela de Início".

Campos obrigatórios para instalabilidade

• name ou short_name — rótulo completo e abreviado exibido sob o ícone. short_name é usado quando o espaço é apertado (máx 12 caracteres).
• start_url — rota aberta quando o usuário toca no ícone da tela inicial. Use "/?source=pwa" para rastrear instalações no analytics.
• display — como a janela é exibida: standalone (sem barra de URL — visual de app nativo), fullscreen (cobre até a status bar — para jogos), minimal-ui (controles mínimos de voltar/recarregar) ou browser (aba comum).
• icons — no mínimo um PNG 192×192 e um 512×512. Sem os dois, o Chrome não exibe o banner de instalação.

Campos opcionais importantes

• theme_color — pinta a status bar do Android e o cabeçalho da splash screen.
• background_color — cor da splash enquanto o bundle JS carrega. Combine com o fundo do body para evitar um flash visível.
• scope — limita quais URLs são consideradas "dentro" do app. Links fora do escopo abrem no navegador, não na janela PWA.
• orientation — portrait, landscape, any ou natural.
• description, categories, lang, dir — metadados usados por app stores (Microsoft Store, Play Store via TWA) e ferramentas de acessibilidade.

Exemplo de manifest.json

{
  "name": "Meu App",
  "short_name": "App",
  "start_url": "/?source=pwa",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#6366f1",
  "background_color": "#ffffff",
  "lang": "pt-BR",
  "icons": [
    { "src": "/icons/192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

Ícones maskable: design com safe zone

O Android permite que cada fabricante aplique uma máscara ao ícone — círculo no Pixel, squircle na Samsung, retângulo arredondado no Android Stock — e recorta tudo o que estiver fora da máscara. O purpose "maskable" avisa ao SO que o ícone foi desenhado pra sobreviver ao recorte. A regra: mantenha todo o conteúdo visual importante (logo, wordmark) dentro de uma safe zone centralizada com 80% da área; os 10% das bordas podem ser cortados. Sem ícone maskable, o Android envolve seu ícone num círculo branco horrível, matando o reconhecimento da marca.

Shortcuts e screenshots

Os shortcuts aparecem no menu de contexto quando o usuário pressiona o ícone (Android) ou clica com o botão direito na barra de tarefas (Windows). É possível declarar até 4 shortcuts, cada um apontando para um deep link dentro do app — ótimo pra "Novo post", "Caixa de entrada", "Configurações", "Buscar".

As screenshots são necessárias para prompts de instalação mais ricos no Chrome 99+. Forneça uma ou mais screenshots wide (1280×720 ou similar) e elas aparecem no diálogo de instalação como uma listagem da Play Store, aumentando muito a conversão.

Service worker é um arquivo à parte

O manifest só descreve o app. Para realmente funcionar offline, interceptar requisições de rede ou receber push notifications, é preciso registrar um service worker separadamente em JavaScript (navigator.serviceWorker.register('/sw.js')). Os critérios completos de instalação do Chrome são: HTTPS + manifest válido + service worker registrado com handler fetch + ícones 192 e 512. O iOS não exige service worker para "Adicionar à Tela de Início", mas as features disponíveis offline continuam limitadas em comparação com o Android.

Referência HTML

<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#6366f1">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

Perguntas frequentes

Funciona no iOS? Parcialmente. O iOS lê start_url, display: standalone e icons, mas ignora shortcuts, screenshots, purpose maskable, push notifications e a maioria das features avançadas. A Apple vem alcançando aos poucos desde o iOS 16.4.

Onde valido o manifest? Em Chrome DevTools → Application → Manifest, que mostra erros de parse e campos obrigatórios ausentes, e na auditoria Lighthouse → PWA, que pontua a instalabilidade ponta a ponta.

O arquivo pode se chamar .webmanifest em vez de .json? Sim — .webmanifest é a extensão oficial e é mais comum em projetos modernos. O servidor deve servir com Content-Type: application/manifest+json para os validadores mais rigorosos.

Por que meu PWA falha no check "Installable" do Lighthouse? Motivos mais comuns: faltam ícones 192 ou 512, falta start_url, service worker não registrado, servido em HTTP em vez de HTTPS, ou o scope do manifest exclui a página atual.

O theme_color muda no dark mode? Sim — use um <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0f172a"> em paralelo ao manifest. O campo do manifest é o default; o meta com media query sobrescreve por esquema.