opengraph-image と twitter-image

opengraph-image と twitter-image ファイル規約により、ルートセグメントの Open Graph および Twitter 画像を設定できます。

これらは、ユーザーがサイトへのリンクをシェアする際にソーシャルネットワークやメッセージングアプリに表示される画像を設定する際に役立ちます。

Open Graph および Twitter 画像を設定する方法は 2 つあります。

画像ファイルを使用する (.jpg、.png、.gif)
コードを使用して画像を生成する (.js、.ts、.tsx)

画像ファイル (.jpg、.png、.gif)

画像ファイルを使用して、セグメント内に opengraph-image または twitter-image 画像ファイルを配置することで、ルートセグメントの共有画像を設定します。

Next.js がファイルを評価し、アプリの <head> 要素に適切なタグを自動的に追加します。

ファイル規約	サポートされるファイル形式
`opengraph-image`	`.jpg`、`.jpeg`、`.png`、`.gif`
`twitter-image`	`.jpg`、`.jpeg`、`.png`、`.gif`
`opengraph-image.alt`	`.txt`
`twitter-image.alt`	`.txt`

補足：

twitter-image ファイルサイズは 5MB を超えてはいけず、opengraph-image ファイルサイズは 8MB を超えてはいけません。画像ファイルサイズがこれらの制限を超える場合、ビルドが失敗します。

`opengraph-image`

任意のルートセグメントに opengraph-image.(jpg|jpeg|png|gif) 画像ファイルを追加します。

<head>

<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />

`twitter-image`

任意のルートセグメントに twitter-image.(jpg|jpeg|png|gif) 画像ファイルを追加します。

<head>

<meta name="twitter:image" content="<generated>" />
<meta name="twitter:image:type" content="<generated>" />
<meta name="twitter:image:width" content="<generated>" />
<meta name="twitter:image:height" content="<generated>" />

`opengraph-image.alt.txt`

opengraph-image.(jpg|jpeg|png|gif) 画像と同じルートセグメントに、付属の opengraph-image.alt.txt ファイルをその代替テキストとして追加します。

opengraph-image.alt.txt

About Acme

<head>

<meta property="og:image:alt" content="About Acme" />

`twitter-image.alt.txt`

twitter-image.(jpg|jpeg|png|gif) 画像と同じルートセグメントに、付属の twitter-image.alt.txt ファイルをその代替テキストとして追加します。

twitter-image.alt.txt

About Acme

<head>

<meta property="twitter:image:alt" content="About Acme" />

コードを使用して画像を生成する (.js、.ts、.tsx)

画像ファイルの使用に加えて、コードを使用してプログラム的に画像を生成できます。

opengraph-image または twitter-image ルートを作成し、デフォルトエクスポートとして関数を実行することで、ルートセグメントの共有画像を生成します。

ファイル規約	サポートされるファイル形式
`opengraph-image`	`.js`、`.ts`、`.tsx`
`twitter-image`	`.js`、`.ts`、`.tsx`

補足：

デフォルトでは、生成された画像は 静的に最適化 されます（ビルド時に生成されキャッシュされます）。ただし、Dynamic API またはキャッシュされないデータを使用する場合は除きます。

generateImageMetadata を使用して、同じファイルで複数の画像を生成できます。

opengraph-image.js と twitter-image.js は特別な Route Handler で、Dynamic API または dynamic config オプションを使用しない限り、デフォルトではキャッシュされます。

画像を生成する最も簡単な方法は、next/og の ImageResponse API を使用することです。

app/about/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// 画像メタデータ
export const alt = 'About Acme'
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 JSX 要素
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        About Acme
      </div>
    ),
    // ImageResponse オプション
    {
      // 便宜上、エクスポートされた opengraph-image
      // サイズ設定を再利用して、ImageResponse の幅と高さを設定できます。
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

<head>

<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="About Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

Props

デフォルトエクスポート関数は以下の props を受け取ります。

`params` (オプション)

ルートセグメントから opengraph-image または twitter-image が配置されているセグメントまでの dynamic route parameters オブジェクトを含むオブジェクトに解決される Promise。

補足：generateImageMetadata を使用する場合、関数は generateImageMetadata が返す項目の 1 つから id 値に解決される Promise である id prop も受け取ります。

app/shop/[slug]/opengraph-image.tsx

TypeScript

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

ルート	URL	`params`
`app/shop/opengraph-image.js`	`/shop`	`undefined`
`app/shop/[slug]/opengraph-image.js`	`/shop/1`	`Promise<{ slug: '1' }>`
`app/shop/[tag]/[item]/opengraph-image.js`	`/shop/1/2`	`Promise<{ tag: '1', item: '2' }>`

Returns

補足：ImageResponse はこの戻り値の型を満たします。

Config エクスポート

opengraph-image または twitter-image ルートから alt、size、contentType 変数をエクスポートして、画像のメタデータを必要に応じて設定できます。

オプション	型
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - image MIME type

`alt`

opengraph-image.tsx

TypeScript

export const alt = 'My images alt text'
 
export default function Image() {}

<head>

<meta property="og:image:alt" content="My images alt text" />

`size`

opengraph-image.tsx

TypeScript

export const size = { width: 1200, height: 630 }
 
export default function Image() {}

<head>

<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

`contentType`

opengraph-image.tsx

TypeScript

export const contentType = 'image/png'
 
export default function Image() {}

<head>

<meta property="og:image:type" content="image/png" />

Route Segment Config

opengraph-image と twitter-image は、Pages および Layouts と同じ route segment configuration オプションを使用できる特別な Route Handler です。

例

外部データを使用する

この例では、params オブジェクトと外部データを使用して画像を生成します。

補足：デフォルトでは、この生成された画像は静的に最適化されます。この動作を変更するには、個別の fetch options またはルートセグメント options を設定できます。

app/posts/[slug]/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
 
export const alt = 'About Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'
 
export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await fetch(`https://.../posts/${slug}`).then((res) =>
    res.json()
  )
 
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

Node.js ランタイムとローカルアセットを使用する

以下の例は、Node.js ランタイムを使用してファイルシステムからローカル画像を取得し、base64 文字列または ArrayBuffer として <img> の src 属性に渡します。ローカルアセットはプロジェクトルートを基準に配置し、例のソースファイルを基準にしません。

app/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'
 
export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'), 'base64')
  const logoSrc = `data:image/png;base64,${logoData}`
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

<img> 要素の src 属性に ArrayBuffer を渡すことは HTML 仕様の一部ではありません。next/og で使用されるレンダリングエンジンはそれをサポートしていますが、TypeScript 定義は仕様に従うため、この機能を使用するには @ts-expect-error ディレクティブまたは同様のものが必要です。

app/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
import { join } from 'node:path'
import { readFile } from 'node:fs/promises'
 
export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {/* @ts-expect-error Satori は <img src> で ArrayBuffer/型付き配列をランタイムで受け入れます */}
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

バージョン履歴

バージョン	変更内容
`v16.0.0`	`params` はオブジェクトに解決する Promise になりました
`v13.3.0`	`opengraph-image` と `twitter-image` 導入時期：v13.3.0