Open Graph and Twitter Cards

Paste a link into Slack, Discord, or iMessage and a card appears — title, site name, image. No JavaScript ran on your page for that; the platform's scraper fetched your URL as plain HTML and read the og: tags out of the server-rendered head. og:image and og:title are the two values that decide the card (with og:description and og:site-name filling the body text), and everything you learned about the Metadata API applies because those tags ride the same head-rendering path.

The exact tags and how the platforms treat them:

Image dimensions are a per-platform contract, and getting them wrong is the most common visible bug. Facebook recommends 1200 × 630 (roughly 1.91:1) and will crop or letterbox anything else; X's large card wants a 2:1 image (1200 × 600 recommended, minimum 300 × 179); the small summary card wants a square thumbnail that survives being rendered at ~144 × 144. The safe universal answer for content sites: one 1200 × 630 image satisfies both platforms' large cards, which is why that resolution became the default everywhere. Two traps around sizing: declaring width/height that disagree with the actual file makes some scrapers mis-lay-out or reject the card, and file-size ceilings (Facebook caps at 8 MB, X at 5 MB) reject oversized exports silently — the card simply renders without the image.

The absolute-URL rule is worth repeating until it is reflex, because it is the bug that generates the most support tickets: relative paths break every scraper. og:image: /og/home.png in the raw HTML means "relative to whatever host fetched it," and platforms resolve it against your metadataBase only if you set it — otherwise Next emits a localhost fallback and the card ships an image URL that resolves for nobody outside your machine. Set metadataBase in the root layout from an env var, verify the emitted tag in the raw response, and consider the whole path tested.

Alt text deserves more than a checkbox answer. Platforms that suppress images (data-saver modes, corporate proxies blocking image hosts) render the alt as the card's fallback; screen readers on the sharing side announce it; and Google's image-search surfaces increasingly key on it. Write it as a caption a human would read — the post's headline plus context — not a keyword list. The remaining pieces of the pipeline, namely where the bytes come from, split into three strategies — static files, generated routes, and per-record generation — and they are the subject of the next two chapters.

One shared /public/og-default.png covers a homepage. It cannot cover 800 blog posts, each of which should preview with its own headline — and hand-exporting images per publish is a content workflow nobody maintains. The App Router answer is a route that renders the card as JSX at request (or build) time, using ImageResponse from next/og:

// app/blog/[slug]/opengraph-image.tsx — file-convention OG image
import { ImageResponse } from "next/og";
import { getPost } from "@/lib/posts";

export const alt = "Blog post preview image";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

export default async function Image(props: { params: Promise<{ slug: string }> }) {
  const { slug } = await props.params;
  const post = await getPost(slug);

  return new ImageResponse(
    (
      <div style={{
        width: "100%", height: "100%", display: "flex",
        flexDirection: "column", justifyContent: "space-between",
        padding: 80, background: "linear-gradient(135deg,#1e293b,#0f172a)", color: "white",
      }}>
        <span style={{ fontSize: 28, opacity: 0.7 }}>ACME BLOG</span>
        <div style={{ fontSize: 72, fontWeight: 700, lineHeight: 1.1 }}>{post.title}</div>
        <span style={{ fontSize: 32, opacity: 0.8 }}>{post.author}</span>
      </div>
    ),
    { ...size }
  );
}

The file convention is the elegant part: placing opengraph-image.tsx beside page.tsx makes Next generate the <meta property="og:image"> tag itself — dimensions, absolute URL, content type, and caching headers included — pointing at the route that renders it. No openGraph.images array to maintain; the image and the tag travel together. (A custom URL shape gets the same result by exporting an ImageResponse from any route file and referencing it explicitly in openGraph.images.)

The JSX here is not arbitrary — it runs through satori, which supports a subset of flexbox and CSS and enforces real constraints that produce the error messages people post about:

Runtime is the operational detail: ImageResponse was built for the Edge Runtime — short-lived, no heavyweight native deps — and current releases also support the Node Runtime, so check your version's docs rather than copying a config from an old tutorial. The route-level exports are how you declare intent (runtime, alt, size, and contentType default sensibly).

Caching decides whether the generation cost is paid once or constantly. A prerendered route generates its card at build — free at request time, frozen until the next deploy. A dynamic route re-renders per request unless you cache it; the sensible defaults are long-lived Cache-Control headers (public, max-age=31536000, immutable when the URL is content-addressed or the content never changes at that path) so platforms' CDN fetches it once per card, not once per share. The generateImageMetadata helper exists for pages that need several cards (one per product angle, say) — it returns an array of image descriptors with distinct ids and alt texts, each rendered by the same component with its own props.

The last design question: what text goes on the card. Front-load the headline — cards render the title twice (image and text), so a card that merely repeats the text line wastes its most valuable pixels. Brand mark, headline, and one distinguishing element (author, category, price) is the template that survives every platform's cropping.

You have three ways to produce a card image, and production sites usually combine them. Choosing wrong shows up as either maintenance pain or broken previews, so hold them apart:

The file convention and the explicit array can coexist deliberately: the convention covers routes with no override, and a page's generateMetadata returns openGraph.images where the card must be custom. Know the precedence — an explicit openGraph.images in metadata wins over the convention for that route — and use it as the escape hatch, not the default, because the convention is what keeps tags and bytes in sync.

Testing is a discipline, because "works in my Slack" is not a test. Every major platform exposes a debugger that refetches its own cache of your card — Facebook's Sharing Debugger, Slack's link unfurling preview, LinkedIn's Post Inspector — and each is the only truthful view of what that platform will render. Two behaviors to expect: scrapers cache aggressively (minutes to hours per platform, independent of your Cache-Control), so a fixed image may still preview wrong for a while, and the debuggers' "scrape again" button is how you bust it. Your own verification loop, before any platform:

curl -s https://acme.com/blog/why-postgres | grep -oE 'property="og:image"[^>]*'
# confirm: absolute https URL, correct dimensions declared, reachable:
curl -sI https://acme.com/blog/why-postgres/opengraph-image | head -3

The curl -I on the image URL is the step people skip: it is where you catch a localhost-fallback URL (missing metadataBase), a 404 from a convention file with a runtime error inside it, a text/html content type from a misconfigured route (some scrapers refuse non-image content types), and cache headers that will make your fix invisible for 24 hours. Combined with the head-level checks from Dynamic generateMetadata, that is the whole verification path — raw HTML tag, then reachable bytes, then platform debugger, in that order.

The accessibility and consistency close: one alt strategy (headline-derived, human-readable) across every card; dimensions declared to match the file; the brand line consistent so a timeline of shares reads as one voice. Two last field-level details show up in audits. og:image should be served over https — scrapers running behind https contexts reject or drop insecure image URLs, so a stray http link (common on migrated sites) silently removes the card image. And when the same image serves several routes, declare og:image:alt per route rather than reusing a generic string: platforms increasingly surface the alt where images are suppressed, and it is the only text a screen-reader user gets about the card's visual content. Neither detail touches ranking directly — social previews are not an SEO ranking factor — but they are the highest-leverage impression most pages get: the card is the click decision for a large share of referral traffic. Below the fold of the card, the crawler-visible work continues with the files that steer discovery itself: Sitemaps and robots.txt.