generateImageMetadata

Core Idea

generateImageMetadata gera múltiplas versões de uma imagem, ou múltiplas imagens, para um único route segment (ex. ícones em vários tamanhos), evitando hard-coding de metadados de imagem.

Key Concepts

• Parâmetros: recebe { params } opcional, objeto com dynamic route params do segmento raiz até o segmento onde a função é chamada.
• Retorno: array de objetos de metadata; cada item deve incluir id (passado como promise para a função geradora de imagem).
• Campos do objeto de metadata: id (obrigatório), alt, size ({ width, height }), contentType.
• Props da função de imagem: recebe id (Promise que resolve para string | number, desde v16.0.0) e params (Promise que resolve para objeto, desde v16.0.0).

Code Examples

import { ImageResponse } from 'next/og'

export function generateImageMetadata() {
  return [
    { contentType: 'image/png', size: { width: 48, height: 48 }, id: 'small' },
    { contentType: 'image/png', size: { width: 72, height: 72 }, id: 'medium' },
  ]
}

export default async function Icon({ id }: { id: Promise<string | number> }) {
  const iconId = await id
  return new ImageResponse(
    <div style={{ width: '100%', height: '100%', display: 'flex' }}>
      Icon {iconId}
    </div>
  )
}

• O que demonstra: gerar duas variações de ícone a partir de uma lista fixa de tamanhos, consumindo id via promise na função default.

export async function generateImageMetadata({ params }: { params: { id: string } }) {
  const images = await getOGImages(params.id)
  return images.map((image, idx) => ({
    id: idx,
    size: { width: 1200, height: 600 },
    alt: image.text,
    contentType: 'image/png',
  }))
}

• O que demonstra: gerar Open Graph images dinamicamente a partir de dados externos e dos dynamic route params.

Reference Tables

Route	URL	params
app/shop/icon.js	/shop	undefined
app/shop/[slug]/icon.js	/shop/1	{ slug: '1' }
app/shop/[tag]/[item]/icon.js	/shop/1/2	{ tag: '1', item: '2' }

Image Metadata Object	Type
id	string (obrigatório)
alt	string
size	{ width: number; height: number }
contentType	string

Key Takeaways

1. id e params passados à função geradora de imagem são promises desde a v16.0.0 (breaking change em relação a versões anteriores).
2. Cada item retornado precisa de um id único para que a função de imagem saiba qual variação gerar.
3. Útil especialmente para ícones e Open Graph images que variam por locale, tamanho ou conteúdo dinâmico.

Connects To

• ImageResponse: usado dentro da função default exportada para efetivamente renderizar a imagem.
• generateMetadata: outra função dinâmica de metadata, para campos textuais (title, description etc).
• File-based Metadata (opengraph-image, icon): convenções de arquivo que generateImageMetadata complementa quando é preciso gerar múltiplas variações.