Imagens de compartilhamento social e ícones
Quando alguém colar o link do site no X, LinkedIn, Slack, Discord ou WhatsApp, uma imagem grande com um título legível deve aparecer. Navegadores e celulares devem mostrar um ícone nítido.
1. Inspecionar
- Pasta App (
src/app/ouapp/),favicon.icoexistente,icon.*,apple-icon.*,opengraph-image.*,twitter-image.*. metadataBaseno layout raiz. Sem ele, as URLs de og:image são relativas e as plataformas sociais as ignoram. Se estiver faltando, adicione-o (veja a skilllaunch-seo, ou definametadataBase: new URL("https://seu-dominio.com")).next.config.*:output: "export"?- Marca: nome, slogan, cor primária, logotipo (SVG preferido). Reutilize tokens de
globals.css. - Leia a documentação correspondente à versão:
node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/01-metadata/opengraph-image.mdnode_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/01-metadata/app-icons.mdnode_modules/next/dist/docs/01-app/03-api-reference/04-functions/image-response.md
2. Imagem Open Graph (para todo o site)
Copie assets/opengraph-image.tsx para app/opengraph-image.tsx e edite os valores da marca. Ele exporta alt, size (1200×630) e contentType, e desenha a imagem com ImageResponse de next/og.
Regras de design para imagens de compartilhamento:
- Título de 3 a 8 palavras, com pelo menos 64 px, alto contraste. Deve ser legível como uma miniatura de 300 px de largura.
- Mantenha o conteúdo importante dentro da área central de 1000×500; algumas plataformas cortam as bordas.
- Marca + nome do domínio em um canto para que as pessoas saibam para onde o link vai.
- Apenas Flexbox:
ImageResponsesuporta um subconjunto de CSS (display: flex, sem grid). Todo elemento com mais de um filho precisa dedisplay: "flex". - Fontes: a fonte padrão funciona imediatamente. Para uma fonte personalizada, carregue um arquivo
.ttf/.otf/.woff(não.woff2) comreadFilee passe-o na opçãofonts, conforme mostrado na documentação. - Limite de tamanho: 8 MB para Open Graph, 5 MB para Twitter. Os PNGs gerados geralmente têm menos de 100 KB.
twitter-image é opcional: quando está faltando, o X usa a imagem Open Graph. Certifique-se de que os metadados raiz definam twitter: { card: "summary_large_image" }.
3. Imagens por página (posts de blog, documentação, páginas de produto)
Adicione opengraph-image.tsx dentro do segmento dinâmico, por exemplo app/blog/[slug]/opengraph-image.tsx. Ele recebe params (uma Promise) e pode carregar o título do post; exporte generateStaticParams do arquivo de imagem para que cada imagem seja pré-renderizada. Mantenha o mesmo modelo para que todos os compartilhamentos pareçam de uma única marca.
Isso é mais importante do que parece: quando uma página define seu próprio openGraph em metadata/generateMetadata, ele substitui o objeto openGraph do pai, e a imagem de compartilhamento raiz desaparece dessa página. Um arquivo opengraph-image no nível do segmento (ou um openGraph.images explícito) resolve o problema.
4. Ícones
Arquivo (em app/) | Tamanho | Finalidade |
|---|---|---|
favicon.ico | 32×32 (vários tamanhos ok) | Aba do navegador, obrigatório na raiz do app |
icon.png ou icon.svg | 512×512 PNG ou SVG | Navegadores modernos, Android |
apple-icon.png | 180×180 | Tela inicial do iOS |
Você também pode gerar icon.tsx / apple-icon.tsx com ImageResponse — veja assets/icon.tsx. Substitua o favicon.ico padrão do create-next-app antes do lançamento; se nenhuma ferramenta .ico estiver disponível, um icon.png de 32×32 mais a remoção do antigo favicon.ico é aceitável.
5. Nota sobre exportação estática
Com output: "export" (testado no Next.js 16.4):
cacheComponentsdeve estar desligado para uma exportação estática, e cada arquivo de imagem gerado (opengraph-image.tsx,icon.tsx,apple-icon.tsx) precisa deexport const dynamic = "force-static";, caso contrário a build falha. Segmentos dinâmicos também precisam degenerateStaticParams.- As imagens geradas são exportadas sem extensão de arquivo (
out/opengraph-image), então hosts estáticos as servem sem cabeçalhoContent-Type(verificado no Cloudflare Pages). Alguns crawlers rejeitam isso. A melhor correção para a imagem de todo o site: abra/opengraph-imageno site em execução, salve-o e commite-o comoapp/opengraph-image.png(depois exclua o.tsx); ele exporta comoopengraph-image.pngcom o tipo correto. O mesmo para ícones (app/icon.png,app/apple-icon.png). Para imagens por post, definaContent-Type: image/pngpara esses caminhos no arquivo de cabeçalhos do host (public/_headersno Cloudflare Pages/Netlify).
6. Verificar
-
npm run builddeve passar. A saída da build lista as rotasopengraph-image. -
Inicie o site (
npm run start, ou sirva a pastaout/) e execute o verificador (Node 18+, sem dependências).<skill-dir>é a pasta que contém este SKILL.md:node <skill-dir>/scripts/check-og.mjs http://localhost:3000/ http://localhost:3000/blog/algum-postEle lê as tags
og:*etwitter:*da página, baixa a imagem e verifica URL absoluta, status HTTP, tamanho do arquivo, dimensões (1200×630),og:image:altetwitter:card. URLs de localhost nas tags são relatadas, pois significam quemetadataBaseestá faltando ou errado para produção. -
Abra a URL da imagem no navegador e olhe para ela. Verifique se o texto é legível quando a janela do navegador está estreita.
-
Após o deploy, diga ao usuário para testar com as próprias ferramentas das plataformas (LinkedIn Post Inspector, o Facebook Sharing Debugger). Elas também atualizam as pré-visualizações em cache.
Relatório
Liste os arquivos de imagem e ícone criados, a saída do verificador e um lembrete de que as plataformas armazenam pré-visualizações em cache: após alterar a imagem, faça uma nova raspagem com as ferramentas acima.