opengraph-image und twitter-image

Die Dateikonventionen opengraph-image und twitter-image ermöglichen das Setzen von Open Graph- und Twitter-Bildern für ein Routensegment.

Sie sind nützlich, um die Bilder festzulegen, die in sozialen Netzwerken und Messaging-Apps erscheinen, wenn ein Benutzer einen Link zu deiner Website teilt.

Es gibt zwei Möglichkeiten, Open Graph- und Twitter-Bilder zu setzen:

Verwendung von Bilddateien (.jpg, .png, .gif)
Generierung von Bildern mittels Code (.js, .ts, .tsx)

Bilddateien (.jpg, .png, .gif)

Um ein geteiltes Bild für ein Routensegment festzulegen, platziere eine opengraph-image oder twitter-image Bilddatei im Segment.

Next.js wertet die Datei aus und fügt automatisch die entsprechenden Tags zum <head>-Element deiner App hinzu.

Dateikonvention	Unterstützte Dateitypen
`opengraph-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`twitter-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`opengraph-image.alt`	`.txt`
`twitter-image.alt`	`.txt`

Hinweis:

Die Dateigröße von twitter-image darf 5MB nicht überschreiten, die von opengraph-image nicht 8MB. Wenn die Bilddateigröße diese Grenzen überschreitet, wird der Build fehlschlagen.

`opengraph-image`

Füge eine opengraph-image.(jpg|jpeg|png|gif) Bilddatei zu einem beliebigen Routensegment hinzu.

<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`

Füge eine twitter-image.(jpg|jpeg|png|gif) Bilddatei zu einem beliebigen Routensegment hinzu.

<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`

Füge eine zugehörige opengraph-image.alt.txt Datei im gleichen Routensegment wie die opengraph-image.(jpg|jpeg|png|gif) Bilddatei als Alt-Text hinzu.

opengraph-image.alt.txt

Über Acme

<head>

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

`twitter-image.alt.txt`

Füge eine zugehörige twitter-image.alt.txt Datei im gleichen Routensegment wie die twitter-image.(jpg|jpeg|png|gif) Bilddatei als Alt-Text hinzu.

twitter-image.alt.txt

Über Acme

<head>

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

Generierung von Bildern mittels Code (.js, .ts, .tsx)

Zusätzlich zur Verwendung von Bilddateien können Bilder auch programmatisch mittels Code generiert werden.

Generiere ein geteiltes Bild für ein Routensegment, indem du eine opengraph-image oder twitter-image Route erstellst, die eine Funktion als Standard-Export bereitstellt.

Dateikonvention	Unterstützte Dateitypen
`opengraph-image`	`.js`, `.ts`, `.tsx`
`twitter-image`	`.js`, `.ts`, `.tsx`

Hinweis:

Standardmäßig werden generierte Bilder statisch optimiert (zur Build-Zeit generiert und gecacht), es sei denn, sie verwenden Dynamic APIs oder nicht-gecachte Daten.

Es können mehrere Bilder in derselben Datei mittels generateImageMetadata generiert werden.

opengraph-image.js und twitter-image.js sind spezielle Route Handler, die standardmäßig gecacht werden, außer sie verwenden eine Dynamic API oder dynamic config Option.

Der einfachste Weg ein Bild zu generieren ist die Verwendung der ImageResponse API von next/og.

app/about/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
 
export const runtime = 'edge'
 
// Image metadata
export const alt = 'Über Acme'
export const size = {
  width: 1200,
  height: 630,
}
 
export const contentType = 'image/png'
 
// Image generation
export default async function Image() {
  // Font
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())
 
  return new ImageResponse(
    (
      // ImageResponse JSX element
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        Über Acme
      </div>
    ),
    // ImageResponse options
    {
      // For convenience, we can re-use the exported opengraph-image
      // size config to also set the ImageResponse's width and height.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: await interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

<head>

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

Props

Die Standard-Exportfunktion erhält die folgenden Props:

`params` (optional)

Ein Objekt, das die dynamischen Route-Parameter vom Root-Segment bis zu dem Segment enthält, in dem sich opengraph-image oder twitter-image befindet.

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

TypeScript

export default function Image({ params }: { params: { slug: string } }) {
  // ...
}

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

Returns

Hinweis: ImageResponse erfüllt diesen Rückgabetyp.

Config exports

Optional können die Metadaten des Bildes durch Export von alt, size und contentType Variablen aus der opengraph-image oder twitter-image Route konfiguriert werden.

Option	Typ
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - image MIME type

`alt`

opengraph-image.tsx

TypeScript

export const alt = 'Alt-Text für mein Bild'
 
export default function Image() {}

<head>

<meta property="og:image:alt" content="Alt-Text für mein Bild" />

`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 und twitter-image sind spezialisierte Route Handler, die dieselben Route Segment Konfigurationsoptionen wie Pages und Layouts verwenden können.

Beispiele

Verwendung externer Daten

Dieses Beispiel verwendet das params Objekt und externe Daten zur Generierung des Bildes.

Hinweis: Standardmäßig wird dieses generierte Bild statisch optimiert. Du kannst die individuellen fetch options oder die Routensegment options konfigurieren, um dieses Verhalten zu ändern.

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

TypeScript

import { ImageResponse } from 'next/og'
 
export const alt = 'Über Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'
 
export default async function Image({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://.../posts/${params.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,
    }
  )
}

Verwendung der Edge Runtime mit lokalen Assets

Dieses Beispiel verwendet die Edge Runtime, um ein lokales Bild im Dateisystem zu laden und als ArrayBuffer an das src-Attribut eines <img>-Elements zu übergeben. Das lokale Asset sollte relativ zum Speicherort der Beispielquelldatei platziert werden.

app/opengraph-image.tsx

TypeScript

import { ImageResponse } from 'next/og'
 
export const runtime = 'edge'
 
export default async function Image() {
  const logoSrc = await fetch(new URL('./logo.png', import.meta.url)).then(
    (res) => res.arrayBuffer()
  )
 
  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

Verwendung der Node.js Runtime mit lokalen Assets

Dieses Beispiel verwendet die Node.js Runtime, um ein lokales Bild im Dateisystem zu laden und als ArrayBuffer an das src-Attribut eines <img>-Elements zu übergeben. Das lokale Asset sollte relativ zum Root-Verzeichnis deines Projekts platziert werden, nicht zum Speicherort der Beispielquelldatei.

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',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

Versionshistorie

Version	Änderungen
`v13.3.0`	`opengraph-image` und `twitter-image` eingeführt.