Next.js Open Graph: Fixing Metadata and Share Images

How Next.js produces Open Graph tags

In the App Router, you never write <meta property="og:..."> by hand. Each layout or page file on the server exports either a static metadata object or an async generateMetadata function. Next.js walks from the root layout down to the page, merges the objects, and prints the result in the head of the HTML it sends. The openGraph key becomes the og: tags and the twitter key becomes the X card tags.

Three rules explain nearly every Open Graph bug in a Next.js site:

1. Relative image paths are resolved against metadataBase. If it is not set, Next.js falls back to a default, typically http://localhost:3000 in development or a deployment address on some hosts, and prints a warning during the build. Crawlers cannot fetch localhost.
2. Merging is shallow. When a page defines openGraph, that whole object replaces the layout's openGraph. It is not combined field by field. A page that sets only openGraph.title loses the layout's image, site name, locale and type.
3. Metadata is a server feature. A file marked 'use client' cannot export metadata, and anything set in the browser with an effect or a head manager after the page loads is invisible to crawlers, which read the HTML and do not run your JavaScript.

On top of that, file conventions let you drop an opengraph-image file into a route folder, or write one as code, and Next.js adds the image tags for you. File-based images take priority over images set in the metadata object, which is useful but also a source of "why is this image not changing" confusion.

Seeing what crawlers receive

Do not debug Open Graph in the browser's element inspector. It shows the page after React has run, which is not what a crawler sees. Fetch the raw HTML from the deployed site instead:

curl -sL -A "facebookexternalhit/1.1" https://example.com/blog/launch-notes \
  | grep -oE '<meta (property|name)="(og|twitter|article):[^"]+"[^>]*>'

Read the output against this list of symptoms:

Then request the image address itself with curl -sI. It should return 200 and an image/png or image/jpeg content type without cookies.

The fix, step by step

Working App Router code

The root layout

// app/shared-metadata.ts
export const baseOpenGraph = {
  siteName: 'Harbour Tide Studio',
  locale: 'en_GB',
  type: 'website' as const,
  images: [{ url: '/images/share-default-1200x630.png', width: 1200, height: 630, alt: 'Harbour Tide Studio logo on a sea-blue background' }],
};
export const baseTwitter = { card: 'summary_large_image' as const, site: '@harbourtide_example' };

// app/layout.tsx
import type { Metadata } from 'next';
import { baseOpenGraph, baseTwitter } from './shared-metadata';

export const metadata: Metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL ?? 'https://example.com'),
  title: { default: 'Harbour Tide Studio', template: '%s | Harbour Tide Studio' },
  openGraph: { ...baseOpenGraph, url: '/' },
  twitter: baseTwitter,
};

A dynamic post page

// app/blog/[slug]/page.tsx
import type { Metadata } from 'next';
import { notFound } from 'next/navigation';
import { baseOpenGraph, baseTwitter } from '../../shared-metadata';
import { getPost } from '@/lib/posts';

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return {
    title: post.title,
    description: post.summary,
    alternates: { canonical: `/blog/${slug}` },
    openGraph: {
      ...baseOpenGraph,
      type: 'article',
      url: `/blog/${slug}`,
      title: post.shareTitle ?? post.title,
      description: post.summary,
      publishedTime: post.publishedAt,
      modifiedTime: post.updatedAt,
      authors: [`/team/${post.authorSlug}`],
    },
    twitter: { ...baseTwitter, title: post.shareTitle ?? post.title, description: post.summary },
  };
}

Two details are easy to miss. The canonical and openGraph.url use the same path, so they cannot drift apart. And this page does not set images: if the folder contains an opengraph-image file, that supplies the image; if not, the spread default does. If you set images here and also have a file, the file wins.

Generated share images with ImageResponse

An opengraph-image.tsx file in a route folder turns JSX into a PNG. It is the cleanest way to give every post its own card with the title written on it.

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';
import { getPost } from '@/lib/posts';

export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';
export const alt = 'Harbour Tide Studio blog post card';

export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const post = await getPost(slug);
  return new ImageResponse(
    (
      <div
        tw="flex h-full w-full flex-col justify-center bg-slate-900 px-24 text-white"
      >
        <div tw="text-3xl opacity-70">Harbour Tide Studio</div>
        <div tw="mt-6 text-7xl font-bold leading-tight">{post?.title ?? 'Blog'}</div>
      </div>
    ),
    { ...size }
  );
}

Things that go wrong with generated images:

• Layout support is limited. The renderer supports a subset of CSS built around flexbox. CSS grid and many advanced properties do not work, and every element with more than one child needs display: flex.
• Fonts must be loaded explicitly. Custom fonts are passed as data in TTF, OTF or WOFF form; WOFF2 is not supported. Load only the weights you use, because the documentation sets a size limit on everything the route bundles.
• Long titles overflow. Clamp the title length or reduce the font size for long headlines so text stays inside the card and within the safe central area.
• Declared size must match. The size export becomes og:image:width and og:image:height. Pass the same values to ImageResponse so the drawn canvas matches the declaration.
• Static export. With output: 'export' there is no server at request time, so image routes for dynamic segments must be generated at build time with generateStaticParams.

The image address Next.js prints includes a short hash query string. That helps with caches, because a changed image gets a new address, but it also means you should never hard-code the address elsewhere.

The Pages Router and older projects

Projects still on the pages/ directory do not have the Metadata API. Tags go in next/head, and the page's data must be available during server rendering through getStaticProps or getServerSideProps, not fetched in the browser after load.

// pages/blog/[slug].tsx
import Head from 'next/head';

export default function Post({ post, siteUrl }) {
  const url = `${siteUrl}/blog/${post.slug}`;
  return (
    <>
      <Head>
        <meta property="og:type" content="article" key="og:type" />
        <meta property="og:url" content={url} key="og:url" />
        <meta property="og:title" content={post.title} key="og:title" />
        <meta property="og:image" content={`${siteUrl}${post.cardPath}`} key="og:image" />
        <meta name="twitter:card" content="summary_large_image" key="twitter:card" />
      </Head>
      {/* page content */}
    </>
  );
}

The key props matter. If _app.tsx prints site-wide defaults with the same keys, the page's tags replace them instead of producing duplicates. Without keys, the head ends up with two og:title tags and platforms pick whichever they meet first. Build absolute addresses yourself here, because there is no metadataBase.

Edge cases specific to Next.js

• Streaming metadata. Recent versions can stream the result of generateMetadata for ordinary browsers, so it arrives after the first part of the page. For recognised crawlers Next.js waits and puts the tags in the head. If a less common preview service receives tags outside the head, its user agent can be added to the htmlLimitedBots setting in next.config.
• Internationalised routes. With app/[locale]/, set openGraph.locale from the route parameter, such as en_GB or fr_FR, rather than hard-coding it in the root layout.
• Preview deployments. If each preview build inherits the production metadataBase, shared preview links show production images, which is usually fine. If it falls back to the preview address, those images may be behind deployment protection.
• Trailing slashes. With trailingSlash: true, make openGraph.url and the canonical include the slash too, so both match the address the site actually serves.
• Images in public/. A path like /images/card.png works once metadataBase is set. Changing the file but not its name leaves platforms and CDNs holding the old version, so rename changed images.