Guide

Next.js Open Graph image (App Router)

The App Router writes share tags for you from two places: an opengraph-image file in a route folder, or openGraph.images in a metadata export. Most broken cards come from a missing metadataBase, a page that overrides the file by accident, or metadata in a client component.

Option 1: an image file in the route folder

The opengraph-image reference says to place an opengraph-image file (.jpg, .jpeg, .png, or .gif) in a route segment, and Next.js adds the tags to the page head: og:image, its type, width, and height. A twitter-image file does the same for twitter:image. An opengraph-image.alt.txt next to it becomes og:image:alt.

app/
  opengraph-image.png        ← default for every page
  opengraph-image.alt.txt
  layout.tsx
  blog/
    [slug]/
      opengraph-image.tsx    ← one image per post, made with code
      page.tsx

The reference caps the files at 8 MB for opengraph-image and 5 MB for twitter-image; a larger file fails the build. Keep it 1200 × 630 and well under 1 MB anyway: Open Graph image size explains why apps drop heavy images.

Option 2: images in metadata

The generateMetadata reference covers the metadata object and the generateMetadata function. Set metadataBase once in the root layout so relative paths become full URLs:

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  metadataBase: new URL('https://www.example.com'),
  openGraph: { images: '/og/default.png' },
  twitter: { card: 'summary_large_image' },
}
// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }) {
  const { slug } = await params
  const post = await getPost(slug)
  return {
    title: post.title,
    description: post.summary,
    openGraph: { images: [post.image] }, // '/og/my-post.png' or a full URL
  }
}

The reference says a relative path in a URL field without metadataBase causes a build error, and an absolute URL in a field ignores metadataBase. Point it at the public site, not a preview host, or every card links to a host people cannot open. Absolute og:image URL covers why apps need the full https:// address.

Why a page shows the wrong image

The opengraph-image reference lists the order. A page's explicit openGraph.images or twitter.images overrides the matching image file, both in its own folder and inherited from parents. Setting images to [], null, or undefined still counts as an override. A shared metadata object copied into a page can carry an images key you forgot about. Remove the property to let the file win.

The opposite problem: a child route that sets openGraph without images, and has no image file, can lose the parent's image, because Next.js merges metadata shallowly. Repeat the image in that page's openGraph, or add an image file to the folder.

Server Components only

The reference says metadata and generateMetadata are only supported in Server Components, because metadata is resolved on the server before the page renders so it can go in the first HTML. A file with 'use client' at the top cannot export them. Since Next.js 15.2, generateMetadata can stream after the page starts, but the reference says Next.js detects HTML-limited bots such as facebookexternalhit by user agent and waits for metadata before responding to them. JavaScript and SPA previews covers why bots need the tags in the HTML.

Read the served HTML

curl -s https://www.example.com/blog/my-post | grep -E 'og:image|twitter:'

next dev serves on localhost, which no app can fetch. Check a deployed URL, or run next build and next start and read what comes back. Then paste the live URL into the form above.

Checklist

  1. metadataBase in the root layout is the public site.
  2. Each shared page gets its image from one place: a file or openGraph.images, not both by accident.
  3. No page sets images: [] or copies a shared object with a stale images key.
  4. Metadata exports live in Server Components, not files marked 'use client'.
  5. After a change, apps that cached the old card get a refresh: see Clear Open Graph cache.

Other frameworks: Astro, Gatsby, Nuxt, and SvelteKit.

FAQ

Where does the image come from?

An opengraph-image file in the route folder (or a parent), or openGraph.images in metadata / generateMetadata. The page's own metadata wins.

Why does the build fail on a relative image path?

metadataBase is not set. Add it to the root layout with your public site.

Can a client component set the image?

No. metadata and generateMetadata work only in Server Components. Move the export to the page or layout file.

What does a CardScope check cost?

A free check shows previews for X, LinkedIn, Slack, Discord, iMessage, Bluesky, Threads, Mastodon, WhatsApp, Telegram, and Microsoft Teams, plus the fix checklist. Pro is $19 once via Stripe Checkout, not a subscription: unlimited checks, a 50-page site audit with a CSV, share links, and PNG export. No account. A sample report shows a full result. A free audit checks the first 3 pages of a site and lists the rest. We parse HTML in memory and discard it — we do not store the page.