ImageResponse

ImageResponse コンストラクタを使用すると、JSX と CSS を使用して動的な画像を生成できます。これは、Open Graph 画像や Twitter カード、その他のソーシャルメディア画像の生成に便利です。

リファレンス

パラメータ

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
 
    // HTTP レスポンスに渡されるオプション
    status?: number = 200
    statusText?: string
    headers?: Record<string, string>
  },
)

例は Vercel OG Playground で確認できます。

サポートされている HTML と CSS の機能

ImageResponse は、flexbox と絶対配置、カスタムフォント、テキスト折り返し、中央揃え、ネストされた画像を含む一般的な CSS プロパティをサポートしています。

サポートされている HTML と CSS の機能の一覧については、Satori のドキュメントを参照してください。

動作

ImageResponse は @vercel/og、Satori、Resvg を使用して HTML と CSS を PNG に変換します。
flexbox と CSS プロパティのサブセットのみがサポートされています。高度なレイアウト（例えば display: grid）は機能しません。
最大バンドルサイズは 500KB です。バンドルサイズには、JSX、CSS、フォント、画像、その他すべてのアセットが含まれます。制限を超える場合は、アセットのサイズを削減するか、ランタイムでフェッチすることを検討してください。
ttf、otf、woff フォント形式のみがサポートされています。フォント解析速度を最大化するために、woff より ttf または otf が推奨されます。

例

Route Handlers

ImageResponse は Route Handlers で使用でき、リクエスト時に動的に画像を生成できます。

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',
            }}
          >
            Welcome to My Site
          </div>
          <div
            style={{
              fontSize: 30,
              color: '#666',
              marginTop: '20px',
            }}
          >
            Generated with Next.js ImageResponse
          </div>
        </div>
      ),
      {
        width: 1200,
        height: 630,
      }
    )
  } catch (e) {
    console.log(`${e.message}`)
    return new Response(`Failed to generate the image`, {
      status: 500,
    })
  }
}

ファイルベースのメタデータ

ImageResponse を opengraph-image.tsx ファイルで使用して、ビルド時または動的にリクエスト時に Open Graph 画像を生成できます。

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(
    (
      // ImageResponse JSX 要素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        My site
      </div>
    ),
    // ImageResponse オプション
    {
      // 便宜上、エクスポートされた opengraph-image
      // サイズ設定を ImageResponse の幅と高さを設定するために再利用できます。
      ...size,
    }
  )
}

カスタムフォント

オプションで fonts 配列を指定することで、ImageResponse でカスタムフォントを使用できます。

app/opengraph-image.tsx

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// 画像メタデータ
export const alt = 'My site'
export const size = {
  width: 1200,
  height: 630,
}
 
export const contentType = 'image/png'
 
// 画像生成
export default async function Image() {
  // フォント読み込み、process.cwd() は Next.js プロジェクトディレクトリです
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )
 
  return new ImageResponse(
    (
      // ...
    ),
    // ImageResponse オプション
    {
      // 便宜上、エクスポートされた opengraph-image
      // サイズ設定を ImageResponse の幅と高さを設定するために再利用できます。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

バージョン履歴

バージョン	変更内容
`v14.0.0`	`ImageResponse` が `next/server` から `next/og` に移動
`v13.3.0`	`ImageResponse` を `next/server` からインポート可能
`v13.0.0`	導入時期：`@vercel/og` パッケージ経由で `ImageResponse` が導入