Capítulo 167 de 456

ImageResponse

Core Idea

Gera imagens dinâmicas (PNG) a partir de JSX e CSS, usado tipicamente para imagens Open Graph, Twitter cards e outras imagens sociais.

Key Concepts

  • ImageResponse: construtor importado de next/og, converte um elemento React + opções em uma resposta de imagem via Satori + Resvg (@vercel/og).
  • width/height: default 1200x630.
  • fonts: array de { name, data, weight, style }; só suporta ttf, otf, woff (ttf/otf parseiam mais rápido).
  • Limite de bundle: 500KB incluindo JSX, CSS, fonts, imagens e outros assets.
  • CSS suportado: apenas flexbox e subconjunto de propriedades (sem display: grid).

Code Examples

// app/opengraph-image.tsx
import { ImageResponse } from 'next/og'

export const alt = 'My site'
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'

export default async function Image() {
  return new ImageResponse(
    (
      <div style={{ fontSize: 128, background: 'white', width: '100%', height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
        My site
      </div>
    ),
    { ...size }
  )
}
  • O que demonstra: gerar imagem Open Graph via arquivo de convenção opengraph-image.tsx, reaproveitando size exportado.
// Fonte customizada lida uma vez em module scope (não depende de request)
const interSemiBold = await readFile(join(process.cwd(), 'assets/Inter-SemiBold.ttf'))

export default async function Image() {
  return new ImageResponse(
    (/* ... */),
    { ...size, fonts: [{ name: 'Inter', data: interSemiBold, style: 'normal', weight: 400 }] }
  )
}
  • O que demonstra: carregar fonte customizada uma única vez fora da função (valor previsível, não depende de request).

Reference Tables

VersionChanges
v14.0.0ImageResponse movido de next/server para next/og
v13.3.0importável de next/server
v13.0.0introduzido via pacote @vercel/og

Anti-patterns

  • Layouts complexos (grid): não suportado, use apenas flexbox e posicionamento absoluto.
  • Exceder 500KB de bundle: reduza assets ou busque-os em runtime em vez de embutir.

Key Takeaways

  1. Use em Route Handlers para gerar imagens em request-time, ou em opengraph-image.tsx para build-time/request-time via convenção de arquivo.
  2. Fontes fixas devem ser lidas em module scope, não a cada chamada.
  3. Consulte o Vercel OG Playground para prototipar o JSX/CSS antes de integrar.

Connects To

  • opengraph-image / twitter-image (file conventions): onde ImageResponse costuma ser usado.
  • Metadata Files: contexto mais amplo de metadados de página.
AnteriorheadersPróximoio