ImageResponse

Le constructeur ImageResponse vous permet de générer des images dynamiques en utilisant JSX et CSS. Cela est utile pour générer des images pour les réseaux sociaux comme les images Open Graph, les cartes Twitter, et plus encore.

Référence

Paramètres

Les paramètres suivants sont disponibles pour ImageResponse :

import { ImageResponse } from 'next/og'

new ImageResponse(
  element: ReactElement,
  options: {
    width?: number = 1200
    height?: number = 630
    emoji?: 'twemoji' | 'blobmoji' | 'noto' | 'openmoji' = 'twemoji',
    fonts?: {
      name: string,
      data: ArrayBuffer,
      weight: number,
      style: 'normal' | 'italic'
    }[]
    debug?: boolean = false

    // Options qui seront passées à la réponse HTTP
    status?: number = 200
    statusText?: string
    headers?: Record<string, string>
  },
)

Des exemples sont disponibles dans le Vercel OG Playground.

Fonctionnalités HTML et CSS prises en charge

ImageResponse prend en charge les propriétés CSS courantes, y compris flexbox et le positionnement absolu, les polices personnalisées, le retour à la ligne du texte, le centrage et les images imbriquées.

Veuillez consulter la documentation de Satori pour une liste des fonctionnalités HTML et CSS prises en charge.

Comportement

ImageResponse utilise @vercel/og, Satori et Resvg pour convertir HTML et CSS en PNG.
Seuls flexbox et un sous-ensemble de propriétés CSS sont pris en charge. Les mises en page avancées (par exemple display: grid) ne fonctionneront pas.
Taille maximale du bundle de 500KB. La taille du bundle inclut votre JSX, CSS, polices, images et tout autre actif. Si vous dépassez la limite, envisagez de réduire la taille des actifs ou de les récupérer au moment de l'exécution.
Seuls les formats de police ttf, otf et woff sont pris en charge. Pour maximiser la vitesse d'analyse des polices, ttf ou otf sont préférés à woff.

Exemples

Gestionnaires de route

ImageResponse peut être utilisé dans les gestionnaires de route pour générer des images dynamiquement au moment de la requête.

app/api/route.js

import { ImageResponse } from 'next/og'

export async function GET() {
  try {
    return new ImageResponse(
      (
        <div
          style={{
            height: '100%',
            width: '100%',
            display: 'flex',
            flexDirection: 'column',
            alignItems: 'center',
            justifyContent: 'center',
            backgroundColor: 'white',
            padding: '40px',
          }}
        >
          <div
            style={{
              fontSize: 60,
              fontWeight: 'bold',
              color: 'black',
              textAlign: 'center',
            }}
          >
            Bienvenue sur mon site
          </div>
          <div
            style={{
              fontSize: 30,
              color: '#666',
              marginTop: '20px',
            }}
          >
            Généré avec Next.js ImageResponse
          </div>
        </div>
      ),
      {
        width: 1200,
        height: 630,
      }
    )
  } catch (e) {
    console.log(`${e.message}`)
    return new Response(`Échec de la génération de l'image`, {
      status: 500,
    })
  }
}

Métadonnées basées sur des fichiers

Vous pouvez utiliser ImageResponse dans un fichier opengraph-image.tsx pour générer des images Open Graph au moment de la construction ou dynamiquement au moment de la requête.

app/opengraph-image.tsx

import { ImageResponse } from 'next/og'

// Métadonnées de l'image
export const alt = 'Mon site'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Génération de l'image
export default async function Image() {
  return new ImageResponse(
    (
      // Élément JSX ImageResponse
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        Mon site
      </div>
    ),
    // Options ImageResponse
    {
      // Par commodité, nous pouvons réutiliser la configuration de taille exportée
      // opengraph-image pour également définir la largeur et la hauteur de ImageResponse.
      ...size,
    }
  )
}

Polices personnalisées

Vous pouvez utiliser des polices personnalisées dans votre ImageResponse en fournissant un tableau fonts dans les options.

app/opengraph-image.tsx

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// Métadonnées de l'image
export const alt = 'Mon site'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Génération de l'image
export default async function Image() {
  // Chargement de la police, process.cwd() est le répertoire du projet Next.js
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  return new ImageResponse(
    (
      // ...
    ),
    // Options ImageResponse
    {
      // Par commodité, nous pouvons réutiliser la configuration de taille exportée
      // opengraph-image pour également définir la largeur et la hauteur de ImageResponse.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

Historique des versions

Version	Changements
`v14.0.0`	`ImageResponse` déplacé de `next/server` vers `next/og`
`v13.3.0`	`ImageResponse` peut être importé depuis `next/server`.
`v13.0.0`	`ImageResponse` introduit via le package `@vercel/og`.

On this page