What is @vercel/og?
@vercel/og is a package designed to generate Open Graph images dynamically. It allows developers to create custom social media preview images on the fly using HTML and CSS, which can be particularly useful for generating unique images for each page or post on a website.
What are @vercel/og's main functionalities?
Generate Open Graph Images
This feature allows you to generate Open Graph images dynamically using HTML and CSS. The code sample demonstrates how to create an image with a custom title passed as a query parameter.
const { ImageResponse } = require('@vercel/og');
export default function handler(req, res) {
const { searchParams } = new URL(req.url, 'http://localhost');
const title = searchParams.get('title') || 'Default Title';
const image = new ImageResponse(
<div style={{
fontSize: 128,
color: 'white',
background: 'black',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
}}>
{title}
</div>,
{
width: 1200,
height: 630,
}
);
res.setHeader('Content-Type', 'image/png');
res.send(image);
}
Other packages similar to @vercel/og
puppeteer
Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It can be used to generate screenshots and PDFs of web pages, which can include Open Graph images. Compared to @vercel/og, Puppeteer offers more flexibility and control over the browser environment but requires more setup and resources.
html-to-image
html-to-image is a library that allows you to convert HTML nodes to images in various formats. It is simpler and more lightweight compared to @vercel/og, but it may not offer the same level of customization and dynamic content generation capabilities.
sharp
Sharp is a high-performance image processing library for Node.js. It can be used to create, manipulate, and convert images. While it does not directly generate images from HTML/CSS like @vercel/og, it can be used in conjunction with other tools to achieve similar results.
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:
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:
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
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/
directorypnpm dev
to start the Next.js app
Package
pnpm i
inside the root directorypnpm build
to build the librarypnpm types
to generate the types
Acknowledgements
This project will not be possible without the following projects: