opengraph-image и twitter-image

Файловые конвенции opengraph-image и twitter-image позволяют задавать изображения Open Graph и Twitter для сегмента маршрута.

Они полезны для установки изображений, которые отображаются в социальных сетях и мессенджерах, когда пользователь делится ссылкой на ваш сайт.

Существует два способа установки изображений Open Graph и Twitter:

Использование файлов изображений (.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> output

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

<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.alt.txt в тот же сегмент маршрута, что и изображение opengraph-image.(jpg|jpeg|png|gif), для указания альтернативного текста.

opengraph-image.alt.txt

About Acme

<head> output

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

`twitter-image.alt.txt`

Добавьте сопровождающий файл twitter-image.alt.txt в тот же сегмент маршрута, что и изображение twitter-image.(jpg|jpeg|png|gif), для указания альтернативного текста.

twitter-image.alt.txt

About Acme

<head> output

<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 APIs или некэшированные данные.

Вы можете сгенерировать несколько изображений в одном файле с помощью generateImageMetadata.

opengraph-image.js и twitter-image.js — это специальные обработчики маршрутов (Route Handlers), которые кэшируются по умолчанию, если не используются Dynamic API или динамические настройки.

Самый простой способ сгенерировать изображение — использовать API ImageResponse из next/og.

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(
    (
      // JSX-элемент ImageResponse
      <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,
        },
      ],
    }
  )
}

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(
    (
      // JSX-элемент ImageResponse
      <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> output

<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" />

Пропсы

Функция, экспортируемая по умолчанию, получает следующие пропсы:

`params` (опционально)

Объект, содержащий параметры динамического маршрута от корневого сегмента до сегмента, в котором расположены opengraph-image или twitter-image.

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

export default function Image({ params }) {
  // ...
}

Маршрут	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' }`

Возвращаемое значение

Полезно знать: ImageResponse соответствует этому типу возвращаемого значения.

Экспорт конфигурации

Вы можете дополнительно настроить метаданные изображения, экспортируя переменные alt, size и contentType из маршрута opengraph-image или twitter-image.

Опция	Тип
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - MIME-тип изображения

`alt`

export const alt = 'My images alt text'

export default function Image() {}

export const alt = 'My images alt text'

export default function Image() {}

<head> output

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

`size`

export const size = { width: 1200, height: 630 }

export default function Image() {}

export const size = { width: 1200, height: 630 }

export default function Image() {}

<head> output

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

`contentType`

export const contentType = 'image/png'

export default function Image() {}

export const contentType = 'image/png'

export default function Image() {}

<head> output

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

Конфигурация сегмента маршрута

opengraph-image и twitter-image — это специализированные обработчики маршрутов (Route Handlers), которые могут использовать те же настройки сегмента маршрута, что и страницы (Pages) и макеты (Layouts).

Примеры

Использование внешних данных

Этот пример использует объект params и внешние данные для генерации изображения.

Полезно знать: По умолчанию это сгенерированное изображение будет статически оптимизировано. Вы можете настроить отдельные опции fetch или настройки сегментов маршрута, чтобы изменить это поведение.

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: { 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,
    }
  )
}

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 }) {
  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,
    }
  )
}

Использование Node.js runtime с локальными ресурсами

Этот пример использует Node.js runtime для загрузки локального изображения из файловой системы и передает его как ArrayBuffer в атрибут src элемента <img>. Локальный ресурс должен располагаться относительно корня вашего проекта, а не местоположения исходного файла примера.

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>
    )
  )
}

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>
    )
  )
}

История версий

Версия	Изменения
`v13.3.0`	Добавлены `opengraph-image` и `twitter-image`.

On this page