Pular para o conteúdo
Documentação do Next.js PT-BR

Metadata e imagens OG

As APIs de Metadata podem ser usadas para definir os metadados do app, para melhorar o SEO e a compartilhabilidade na web, e incluem:

  1. O objeto metadata estático
  2. A função generateMetadata dinâmica
  3. Convenções de arquivo especiais que podem ser usadas para adicionar favicons e imagens OG estáticos ou gerados dinamicamente.

Com todas as opções acima, o Next.js gera automaticamente as tags <head> relevantes para a página, que podem ser inspecionadas nas ferramentas de desenvolvedor do navegador.

As exportações do objeto metadata e da função generateMetadata só funcionam em Server Components.

Campos padrão

Há duas tags meta padrão que são sempre adicionadas, mesmo que uma rota não defina metadados:

  • A tag meta charset define a codificação de caracteres do site.
  • A tag meta viewport define a largura e a escala da viewport do site para se adaptar a diferentes dispositivos.
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />

Os demais campos de metadados podem ser definidos com o objeto Metadata (para metadados estáticos) ou com a função generateMetadata (para metadados gerados).

Metadados estáticos

Para definir metadados estáticos, exporte um objeto Metadata de um arquivo layout.js ou page.js estático. Por exemplo, para adicionar um título e uma descrição à rota do blog:

app/blog/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Blog',
  description: '...',
}

export default function Layout() {}

Você pode ver a lista completa de opções disponíveis na documentação de generateMetadata.

Metadados gerados

Você pode usar a função generateMetadata para fazer fetch de metadados que dependem de dados. Por exemplo, para buscar o título e a descrição de um post específico do blog:

app/blog/[slug]/page.tsx
import type { Metadata, ResolvingMetadata } from 'next'

type Props = {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}

export async function generateMetadata(
  { params, searchParams }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const slug = (await params).slug

  // fetch post information
  const post = await fetch(`https://api.vercel.app/blog/${slug}`).then((res) =>
    res.json()
  )

  return {
    title: post.title,
    description: post.description,
  }
}

export default function Page({ params, searchParams }: Props) {}

Metadados em streaming

Em páginas renderizadas dinamicamente, o Next.js faz streaming dos metadados separadamente, injetando-os no HTML assim que generateMetadata resolve, sem bloquear a renderização da interface.

Fazer streaming dos metadados melhora a performance percebida, pois permite que o conteúdo visual chegue primeiro.

O streaming de metadados é desativado para bots e crawlers que esperam que os metadados estejam na tag <head> (por exemplo, Twitterbot, Slackbot, Bingbot). Eles são detectados pelo header User Agent da requisição recebida.

Você pode personalizar ou desativar completamente o streaming de metadados com a opção htmlLimitedBots no arquivo de configuração do Next.js.

Páginas com prerendering não usam streaming, já que os metadados são resolvidos no build.

Saiba mais sobre streaming de metadados.

Memoização de requisições de dados

Pode haver casos em que você precisa buscar os mesmos dados para os metadados e para a própria página. Para evitar requisições duplicadas, você pode usar a função cache do React para memoizar o valor retornado e buscar os dados só uma vez. Por exemplo, para buscar as informações do post do blog tanto para os metadados quanto para a página:

app/lib/data.ts
import { cache } from 'react'
import { db } from '@/app/lib/db'

// getPost will be used twice, but execute only once
export const getPost = cache(async (slug: string) => {
  const res = await db.query.posts.findFirst({ where: eq(posts.slug, slug) })
  return res
})
app/blog/[slug]/page.tsx
import { getPost } from '@/app/lib/data'

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  return {
    title: post.title,
    description: post.description,
  }
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  return <div>{post.title}</div>
}

Metadados baseados em arquivos

Os seguintes arquivos especiais estão disponíveis para metadados:

Você pode usá-los para metadados estáticos ou gerar esses arquivos programaticamente com código.

Favicons

Favicons são pequenos ícones que representam o site em favoritos e resultados de busca. Para adicionar um favicon ao app, crie um favicon.ico e adicione-o na raiz da pasta app.

Arquivo especial favicon dentro da pasta App, com arquivos layout e page irmãosArquivo especial favicon dentro da pasta App, com arquivos layout e page irmãos

Você também pode gerar favicons programaticamente com código. Veja a documentação de favicons para mais informações.

Imagens Open Graph estáticas

Imagens Open Graph (OG) são imagens que representam o site nas redes sociais. Para adicionar uma imagem OG estática ao app, crie um arquivo opengraph-image.jpg na raiz da pasta app.

Arquivo especial de imagem OG dentro da pasta App, com arquivos layout e page irmãosArquivo especial de imagem OG dentro da pasta App, com arquivos layout e page irmãos

Você também pode adicionar imagens OG para rotas específicas criando um opengraph-image.jpg mais fundo na estrutura de pastas. Por exemplo, para criar uma imagem OG específica para a rota /blog, adicione um arquivo opengraph-image.jpg dentro da pasta blog.

Arquivo especial de imagem OG dentro da pasta blogArquivo especial de imagem OG dentro da pasta blog

A imagem mais específica terá precedência sobre as imagens OG acima dela na estrutura de pastas.

Outros formatos de imagem, como jpeg, png e gif, também são aceitos. Veja a documentação de imagens Open Graph para mais informações.

Imagens Open Graph geradas

O construtor ImageResponse permite gerar imagens dinâmicas usando JSX e CSS. Isso é útil para imagens OG que dependem de dados.

Por exemplo, para gerar uma imagem OG única para cada post do blog, adicione um arquivo opengraph-image.tsx dentro da pasta blog/[slug] e importe o construtor ImageResponse de next/og:

app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
import { getPost } from '@/app/lib/data'

// Image metadata
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Image generation
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)

  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    )
  )
}

ImageResponse oferece suporte às propriedades CSS comuns, incluindo flexbox e posicionamento absoluto, fontes personalizadas, quebra de texto, centralização e imagens aninhadas. Veja a lista completa de propriedades CSS com suporte.

Bom saber:

  • Exemplos estão disponíveis no Vercel OG Playground.
  • ImageResponse usa @vercel/og, satori e resvg para converter HTML e CSS em PNG.
  • Só há suporte a flexbox e a um subconjunto de propriedades CSS. Layouts avançados (por exemplo, display: grid) não funcionam.

Referência da API

Saiba mais sobre as APIs de Metadata mencionadas nesta página.