@vercel/og
TypeScript icon, indicating that this package has built-in type declarations

0.6.2 • Public • Published

Open Graph Image Generation

Generate Open Graph images with Vercel’s API route functions

Quick Start

Install @vercel/og, then use it inside an API route in your Next.js project:

// /pages/api/og.jsx
import { ImageResponse } from '@vercel/og'

export default function () {
  return new ImageResponse(
    (
      <div
        style={{
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: 128,
          background: 'lavender',
        }}
      >
        Hello!
      </div>
    )
  )
}

Then run next dev and access localhost:3000/api/og, the React element will be rendered and responded as a PNG from that endpoint:

Rendered OG image

Read more about the API, supported features and check out the examples in the following sections.

API Reference

@vercel/og supports both Node.js Runtime and Edge Runtime.

The package exposes an ImageResponse constructor, with the following options available:

import { ImageResponse } from '@vercel/og'

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

    // Options that will be passed to the HTTP response
    status?: number = 200
    statusText?: string
    headers?: Record<string, string>
  },
)

When running in production, these headers will be included by @vercel/og:

'content-type': 'image/png',
'cache-control': 'public, immutable, no-transform, max-age=31536000',

During development, the cache-control: no-cache, no-store header is used instead.

Supported HTML and CSS Features

Please refer to Satori’s documentation for a list of supported HTML and CSS features.

By default, @vercel/og only has the Noto Sans font included. If you need to use other fonts, you can pass them in the fonts option. Check the Custom Font example below for more details.

Examples

Development / Contributing

Playground

  • pnpm i inside the playground/ directory
  • pnpm dev to start the Next.js app

Package

  • pnpm i inside the root directory
  • pnpm build to build the library
  • pnpm types to generate the types

Acknowledgements

This project will not be possible without the following projects:


Package Sidebar

Install

npm i @vercel/og

Weekly Downloads

140,211

Version

0.6.2

License

MPL-2.0

Unpacked Size

6.22 MB

Total Files

17

Last publish

Collaborators

  • matt.straka
  • ijjk
  • quietshu
  • vercel-release-bot
  • nick.tracey
  • matheuss
  • chriswdmr
  • snokohn
  • zeit-bot