Dynamic OG Images for Next.js & Vercel (3 Production Patterns)

Open Graph images are the first thing most people see when a link to your app gets shared - on Slack, Twitter, LinkedIn, iMessage, anywhere a URL gets unfurled into a preview card. A static OG image works fine for a marketing homepage. It falls apart for anything dynamic: blog posts, product pages, user profiles, dashboards, or any route where the content changes per-request. For those, you need OG images generated programmatically, per route, and that generation needs to be fast enough not to introduce noticeable latency.

There are three common production patterns for this in the Next.js and Vercel ecosystem, and they have meaningfully different trade-offs. This post walks through all three.

Pattern 1: Edge Runtime Generation with @vercel/og

The most common approach for new Next.js projects is generating OG images directly at the edge using @vercel/og, which wraps Satori - a library that converts JSX and CSS into SVG, then rasterizes to PNG.

// app/api/og/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get('title') ?? 'Default Title';

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          height: '100%',
          width: '100%',
          alignItems: 'center',
          justifyContent: 'center',
          background: '#0f172a',
          color: '#ffffff',
          fontSize: 64,
        }}
      >
        {title}
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

The advantage here is speed and integration. It runs at the edge, has no cold start in the traditional serverless sense, and stays entirely within your Next.js deployment - no external service, no additional API keys.

The limitation is the rendering engine itself. Satori implements a subset of CSS - flexbox layouts work well, but grid, certain pseudo-selectors, and complex visual effects are not supported. For straightforward card layouts with text, a background, and a logo, this is rarely a problem. For OG images that need to closely mirror your actual product UI - a chart, a live dashboard state, a complex component - you will hit the limits of what Satori can render.

Pattern 2: Screenshot-Based Generation via External API

The second pattern sidesteps rendering limitations entirely by capturing an actual screenshot of a dedicated visual route. You build a route specifically designed to look good as a 1200x630 card - /og/[slug] - and instead of reimplementing that layout in Satori's CSS subset, you screenshot the real rendered page using full browser rendering.

// Fetching a screenshot for use as an OG image source
async function getOgImageUrl(slug: string) {
  const targetUrl = `https://yourapp.com/og/${slug}`;

  const response = await fetch('https://api.snapshot-provider.com/v1/capture', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SCREENSHOT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: targetUrl,
      viewport: { width: 1200, height: 630 },
      format: 'png',
      wait_until: 'networkidle2',
    }),
  });

  const data = await response.json();
  return data.image_url;
}

This is the right approach when your card design needs full CSS - real grid layouts, web fonts that Satori does not support well, charts rendered with a JS charting library, or any visual complexity beyond what an SVG-based renderer handles cleanly. Using an Open Graph image API for this means you get a genuine browser rendering pipeline behind the capture rather than reimplementing your design twice - once in your app, once in Satori-compatible JSX.

The trade-off is latency and an external dependency. A real browser render-and-capture cycle takes longer than Satori's SVG-to-PNG path, and you are now relying on a third-party service's uptime for a piece of your social sharing pipeline. This is exactly why caching matters more here than in the edge-rendering pattern - more on that below.

Pattern 3: Hybrid Middleware-Triggered Generation

The third pattern combines the two: use edge generation as the default, fast path, and fall back to a screenshot-based render only for routes that genuinely need it. A middleware function inspects the request and routes accordingly.

This works well when most of your OG images are simple (text + background, handled fine by Satori) but a subset of routes - say, pages with embedded data visualizations - need full rendering fidelity. Middleware checks a route pattern or a flag in your CMS data and dispatches to the appropriate generation path, keeping the fast case fast and reserving the heavier screenshot path for where it is actually needed.

Performance Engineering

Cache by route slug, not by request. OG images for a given piece of content rarely change between requests. Generate once per slug, cache aggressively, and invalidate only when the underlying content changes - on publish or edit, not on every social platform's crawl request. A CDN cache key based on the slug (and any meaningful query parameters) turns most of your traffic into cache hits regardless of which generation pattern you use.

Always have a fallback graphic. Generation can fail - a timeout, a missing parameter, an external API hiccup. Social platforms that fail to load an og:image URL either show nothing or fall back to a generic favicon, both of which look broken. Configure a static fallback image and route any generation failure to it rather than returning a 500 or an empty response.

Manage cold starts deliberately. Edge functions for OG generation are typically fast, but serverless functions calling external screenshot APIs can have cold start overhead on infrequently hit routes. If your screenshot-based pattern serves low-traffic long-tail content, consider pre-generating OG images at build or publish time rather than generating on first request - this removes cold start latency from the user-facing path entirely, since the crawler hitting the link preview never triggers generation directly.

Choosing a Pattern

For most applications, start with edge generation - it covers the majority of OG image needs with minimal infrastructure and no external dependency. Reach for screenshot-based generation specifically when your card design requires rendering fidelity that Satori cannot provide. Use the hybrid pattern once you have enough routes in each category that maintaining both paths is worth the added complexity.

The decision is rarely all-or-nothing in practice - most production Next.js apps running at scale end up with some version of the hybrid model, even if it starts as a single edge-rendered template.

推荐订阅源