The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →In the Next.js App Router, put a supported opengraph-image file in the route segment you want to represent, or generate one with opengraph-image.tsx and ImageResponse. Next.js creates the Open Graph metadata tags for these file conventions automatically. Use the metadata API instead when you already have an image URL or need to compute metadata for a route.
Choose the right way to add an Open Graph image
| Approach | Use it when | Where the image comes from |
|---|---|---|
| Static file convention | The image is fixed, or you want an image colocated with a route. | A supported image file in the route segment. |
| Generated file convention | The card should show route-specific or data-driven content, such as a post title. | A React element rendered by ImageResponse. |
| Metadata API | You already have a hosted image URL or need to calculate metadata in code. | An absolute image URL returned by metadata or generateMetadata. |
The examples below use the App Router. Next.js introduced the opengraph-image and twitter-image conventions in v13.3.0; current v16 documentation represents generated-image params as a promise. Check your installed version before copying signatures into an older project.
As an Amazon Associate I earn from qualifying purchases.
How do I add a fixed OG image to a Next.js page?
Place an image named opengraph-image.jpg, opengraph-image.jpeg, opengraph-image.png, or opengraph-image.gif in the App Router segment for the page. For example:
app/
├── opengraph-image.png # default for routes under app/
├── blog/
│ ├── opengraph-image.jpg # default for blog routes
│ └── my-post/
│ └── page.tsxThe root image serves as a default for routes beneath that segment. A more specific image in a nested segment takes precedence for routes there. Next.js generates the relevant head metadata, including og:image and associated image type and dimensions.
#1 Best Overall
Set alt text for a static image
To provide alt text, add a text file with the matching name and the .alt.txt suffix beside the image:
app/blog/opengraph-image.jpg
app/blog/opengraph-image.alt.txtPut the description in the text file. The static Open Graph image limit in the current Next.js documentation is 8 MB; a larger file fails the build. The separate documented limit for a Twitter image is 5 MB. These are framework file limits, not universal social-platform image-size recommendations.
Rank #2
How do I generate a route-specific Open Graph image?
Create opengraph-image.tsx in the route segment and return an ImageResponse from next/og. Export alt, size, and contentType to describe the generated image:
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() {
return new ImageResponse(
<div
style={{
fontSize: 48,
background: 'white',
width: '100%',
height: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
}}
>
About Acme
</div>,
{ ...size }
)
}The 1200 × 630 dimensions above are the size used in the Next.js example; they are not established here as a universal requirement for every social network or messaging app. For route-dependent output, the generated-image function can receive route parameters. Current Next.js v16 documentation uses promise-based params; confirm the signature for your project version before implementing a dynamic example. Generated images are statically optimized by default unless they use Dynamic APIs or uncached data.
When should I use metadata or generateMetadata?
Use the metadata API when an image is already hosted at a URL, or when values should be returned based on route parameters or fetched data. A static metadata export suits fixed values; generateMetadata can calculate them. These exports are supported in Server Components.
import type { Metadata } from 'next'
export const metadata: Metadata = {
openGraph: {
title: 'About Acme',
images: [
{
url: 'https://example.com/images/about-card.png',
width: 1200,
height: 630,
alt: 'About Acme',
},
],
},
}Use an absolute URL for the image, as required by the Next.js metadata example. If the image belongs with the route and is a file rather than an existing hosted URL, the file convention is usually the more direct option because its image metadata stays associated with that route.
Preserve parent Open Graph values
A child route that defines its own openGraph object replaces the parent’s openGraph object; fields omitted by the child are not merged automatically. If a child adds an image but should retain a shared title, description, or other Open Graph field, include those values in the child’s object or build the child metadata from a shared object deliberately.
Check the result and troubleshoot common problems
- The expected image does not appear in the generated metadata: Check that the file is named using a supported convention and sits in the route segment intended to own it. A more specific nested file overrides the higher-level default.
- The build fails on a static image: Check that the Open Graph file is no larger than the documented 8 MB limit and that the extension is supported.
- Some shared Open Graph values disappear on a child page: The child may define a replacement
openGraphobject. Add the values that need to persist or reuse a shared object. - A metadata API image is not resolving as expected: Verify that the image URL is absolute.
- A generated image errors after copying an example: Check the installed Next.js version and the generated function’s parameter signature. Current v16 documentation uses promise-based
params, unlike the prior form.
These steps configure the metadata and image response in your application. They do not establish how a particular social network will choose to display or cache a preview.
Or skip the browser setup
If you need a screenshot of a page as it renders in a browser, ScreenshotNeo can return an image with one GET request. It is a screenshot API, not a replacement for configuring your page’s Open Graph metadata.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status. An MCP server provides screenshot, page-info, and PDF-capture tools for AI agents.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo, or sign up free.
Recommended Free Tools
Frequently Asked Questions
Do I need to add Open Graph tags manually when I use an opengraph-image file?
No. The App Router file convention causes Next.js to generate the relevant metadata tags for the image.
Can a page have both a parent default image and a route-specific image?
Yes. Put the default in a higher route segment and the more specific file in the nested segment; the nested file takes precedence for its routes.
Are 1200 × 630 pixels guaranteed to work everywhere?
No universal social-platform requirement is established here. That is the size in the Next.js generated-image example, not a guarantee for every service.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors
