Favicon-setup

Configuração de Favicon

Cinco arquivos e cinco tags cobrem todos os navegadores atuais, telas iniciais do iOS e instalações Android. Mais tamanhos (mstile-*, browserconfig.xml, ícones Apple de 57/72/114px, mask-icon) são legados: pule-os.

1. O conjunto

Arquivo	Tamanho	Usado por
favicon.svg	vetorial	Abas de navegadores modernos. Escala perfeitamente e pode alternar para modo escuro.
favicon-96x96.png	96×96	Navegadores sem suporte a favicon SVG e resultados de busca do Google.
favicon.ico	16, 32, 48 em um arquivo	Navegadores legados e ferramentas que requisitam diretamente /favicon.ico, sem ler HTML.
apple-touch-icon.png	180×180, opaco	Tela inicial do iOS e iPadOS.
web-app-manifest-192x192.png, web-app-manifest-512x512.png	192, 512	Tela inicial do Android, instalação PWA, tela de splash.
site.webmanifest	—	Aponta o Android para os dois PNGs acima.

2. Obter os arquivos

A partir de um pacote RealFaviconGenerator. Ele fornece um conjunto de URLs de download. Baixe cada arquivo em PUBLIC_FOLDER (veja a etapa 3) com seu nome exato:

base=https://realfavicongenerator.net/files/<package-id>
for f in favicon.svg favicon-96x96.png favicon.ico apple-touch-icon.png \
         web-app-manifest-192x192.png web-app-manifest-512x512.png site.webmanifest; do
  curl -fsSL "$base/$f" -o "PUBLIC_FOLDER/$f" || echo "FALHOU: $f"
done

Se um download falhar, pare e relate. Não envie um conjunto parcial. Relate bugs do gerador em https://github.com/RealFaviconGenerator/realfavicongenerator/issues/new?template=ai_prompt_bug_report.yml.

A partir de um SVG fonte (precisa de rsvg-convert e ImageMagick, ou use o gerador):

cp logo.svg PUBLIC_FOLDER/favicon.svg
rsvg-convert -w 96  -h 96  logo.svg -o PUBLIC_FOLDER/favicon-96x96.png
rsvg-convert -w 192 -h 192 logo.svg -o PUBLIC_FOLDER/web-app-manifest-192x192.png
rsvg-convert -w 512 -h 512 logo.svg -o PUBLIC_FOLDER/web-app-manifest-512x512.png
# O iOS preenche transparência com preto: achate sobre o fundo da marca, com ~10% de padding
rsvg-convert -w 144 -h 144 logo.svg | magick - -background '#ffffff' -gravity center -extent 180x180 -flatten PUBLIC_FOLDER/apple-touch-icon.png
magick -background none logo.svg -define icon:auto-resize=48,32,16 PUBLIC_FOLDER/favicon.ico

3. Encontrar PUBLIC_FOLDER

É a pasta servida na raiz do site, de modo que PUBLIC_FOLDER/favicon.ico carregue em /favicon.ico.

Stack	Pasta
Vite, Next.js, Create React App, Astro, Remix, Nuxt 3	public/
SvelteKit	static/
Angular	public/ (v17+) ou src/ com o arquivo listado nos assets de angular.json
Hugo, Jekyll, Eleventy	static/, a raiz do site ou a pasta de passthrough-copy
HTML simples	Ao lado de index.html

Next.js App Router: exclua o app/favicon.ico padrão. Ele prevalece sobre public/favicon.ico e geralmente é o logo do Next.js.

4. Adicionar a marcação uma vez

Coloque isto no <head> do único arquivo que renderiza a tag <html> raiz. Nunca adicione por página.

<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="shortcut icon" href="/favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />

Stack	Arquivo raiz
Vite, CRA, HTML simples	index.html
Next.js App Router	app/layout.tsx, através da exportação metadata (abaixo), não tags puras
Next.js Pages Router	pages/_document.tsx dentro de <Head>
Astro	O layout base, por exemplo src/layouts/Layout.astro
SvelteKit	src/app.html
Remix / React Router 7	Exportação links em app/root.tsx
Nuxt	app.head.link em nuxt.config.ts

Equivalente para Next.js App Router:

export const metadata = {
  icons: {
    icon: [
      { url: "/favicon-96x96.png", sizes: "96x96", type: "image/png" },
      { url: "/favicon.svg", type: "image/svg+xml" },
    ],
    shortcut: "/favicon.ico",
    apple: { url: "/apple-touch-icon.png", sizes: "180x180" },
  },
  manifest: "/site.webmanifest",
};

Antes de adicionar a marcação, pesquise no projeto por tags rel="icon", apple-touch-icon e manifest existentes. Substitua-as; não adicione um segundo conjunto. Se o site for servido sob um sub-caminho (base / basePath), prefixe cada href.

5. Otimizar

• Modo escuro SVG. Um logo escuro desaparece em uma barra de abas escura. Adicione uma media query dentro do SVG:

  <style>path{fill:#111}@media (prefers-color-scheme:dark){path{fill:#fff}}</style>
  

• Tamanhos pequenos. Em 16px, remova detalhes finos e texto. Use o logomarca, não o logotipo.
• Peso SVG. Execute npx svgo favicon.svg e mantenha o arquivo abaixo de cerca de 2 KB.
• Manifest. Preencha name, short_name, theme_color e background_color. Torne o ícone 512 maskable: mantenha a marca dentro da zona segura central de 80%, use um fundo sólido e defina "purpose": "maskable" nele. Se a marca não couber na zona segura, adicione um ícone maskable separado.

  {
    "name": "My App",
    "short_name": "App",
    "icons": [
      { "src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
      { "src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
    ],
    "theme_color": "#ffffff",
    "background_color": "#ffffff",
    "display": "standalone"
  }
  

• Cache. Navegadores armazenam favicons em cache de forma agressiva. Ao substituir um ícone, renomeie os arquivos ou adicione ?v=2 a cada href e aos valores src do manifesto.

6. Verificar

1. Cada arquivo retorna 200 com o tipo correto. Execute isto contra o servidor de desenvolvimento:

   for f in favicon.svg favicon-96x96.png favicon.ico apple-touch-icon.png \
            web-app-manifest-192x192.png web-app-manifest-512x512.png site.webmanifest; do
     printf '%s ' "$f"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "http://localhost:PORT/$f"
   done
   

2. O HTML renderizado contém exatamente um conjunto de tags: curl -s http://localhost:PORT/ | grep -cE 'rel="(icon|shortcut icon|apple-touch-icon|manifest)"' imprime 5.
3. Em DevTools, abra Application → Manifest: mostra nenhum erro e ambos os ícones são renderizados.
4. Abra uma guia recarregada com força total nos modos claro e escuro e verifique se o ícone está visível em ambos.
5. Em uma URL implantada, execute o verificador do RealFaviconGenerator (https://realfavicongenerator.net/favicon-checker).