noi

next-og-image

Generate Open Graph protocol images using Next.js and React components.

Showing:

Popularity

Downloads/wk

18

GitHub Stars

7

Maintenance

Last Commit

2mos ago

Contributors

0

Package

Dependencies

2

License

MIT

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

Next OG Image

Generate Open Graph protocol images for your website using Next.js and React components.

Inspired by Vercel's Open Graph image service 🙂.

Usage

1. Install the next-og-image package

npm install next-og-image

2. Create a Next.js API route

The API route will generate and serve Open Graph images.

It can be placed in any directory inside of pages/api, but it must be named [...path].ts.

For example:

pages/api/og-image/[...path].ts

Learn more about Next.js API routes and catch-all routes.

4. Initialise Next OG Image

Place the following code inside of the [...path].ts API route:

import { createHandler } from 'next-og-image'
const ogImageHandler = createHandler()
export default ogImageHandler

The createHandler function returns a Next.js API handler function.

5. Create a page to render an OG image

Next OG Image converts any Next.js page to a PNG image suitable for use as an Open Graph image.

You can create a Next.js page at any location to render an OG image.

You may want to tell search engines not to index the page, because it's not particularly useful beyond rendering an OG image.

The image generated is 2048x1260 pixels. You may need to make the contents of you page larger than you'd expect. On my website, I have used the zoom property to quickly and easily scale up my design system components.

Here is an example from my personal site: https://ash.gd/this-is-my-jam/28252440-993a-4096-9f7b-9588ff4374ac/og-image.

The PNG version can be accessed at: https://og-image.ash.gd/api/this-is-my-jam/28252440-993a-4096-9f7b-9588ff4374ac/og-image.png.

Use the following URL structure to link to an OG image:

[url]/api/[apiRoute]/[ogPath].png
TokenDescriptionExample
urlWebsite URL.https://ash.gd
apiRoutePath to OG image API route.og-image
ogPathPath to OG image page.this-is-my-jam/28252440-993a-4096-9f7b-9588ff4374ac/og-image

For example: https://og-image.ash.gd/api/this-is-my-jam/28252440-993a-4096-9f7b-9588ff4374ac/og-image.png.

Image size

The generated image is 1200x600 pixels, adhering to the 2:1 aspect ratio of Twitter's summary card with large image format.

If you have different requirements for the image size, please comment on #11.

Passing props to the source page

You can use query parameters to customise the source page. Any query parameters included in the request are passed through to the source page, where you can access them using a Next.js data fetching function, or the Next.js router.

Environment variables

Next OG Image must know your website URL in order to load a page to snapshot.

If you deploy to Vercel, this will be handled automatically using the VERCEL_URL environment variable.

If you do not deploy to Vercel, are testing locally, or want to override the URL, you can do so by setting the OG_IMAGE_BASE_URL environment variable.

NameDescriptionRequired
OG_IMAGE_BASE_URLBase URL used to load source pages. If deployed to Vercel, the VERCEL_URL environment variable is used by default.No
OG_IMAGE_CHROME_EXECUTABLE_PATHPath to Chrome. Not required when deployed to Vercel, AWS, or GCP.No

Caching

Generated images are cached by the CDN and the client for one year.

Running outside of Vercel, AWS, or GCP

To run Next OG Image outside of Vercel, AWS, or GCP, set the OG_IMAGE_CHROME_EXECUTABLE_PATH environment variable.

For example, on macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100