Next.js OG Image Generation: @vercel/og, Edge Runtime, Custom Fonts
Generate dynamic Open Graph images in Next.js 14+ using @vercel/og on the Edge Runtime — custom fonts, JSX templates, and zero cold starts explained.
Why Dynamic OG Images Actually Matter
You've shipped the component, written the copy, deployed the page. Then someone shares the link on Twitter and it renders as a blank gray rectangle. That's a social preview failure — and it's tanking your click-through rate without you ever knowing. Open Graph images are the first impression your content makes outside your own site, and static screenshots don't cut it for content that changes.
In practice, the gap between a hand-crafted 1200×630 PNG and a dynamically generated image that knows the article title, author, and publish date is the difference between 3% and 11% CTR on the same content. Those numbers are from real A/B tests run in 2024 on editorial sites. Dynamic OG images aren't a nice-to-have anymore.
Next.js solved this cleanly with the ImageResponse API shipped inside @vercel/og. You write JSX, the Edge Runtime renders it to a PNG in under 80ms with zero cold starts. No headless browser, no Puppeteer, no $40/month screenshot service. Worth noting: this works on Vercel's free tier with generous limits.
That said, the API has some sharp edges — font loading is different from what you're used to, not all CSS is supported, and the file routing changed between Next.js 13 and 14. Let's go through each piece so you don't hit the same walls I did.
Setting Up @vercel/og in a Next.js App Router Project
First, the install. @vercel/og ships as a separate package but since Next.js 13.3 the ImageResponse class is also re-exported directly from next/og — which means zero extra dependencies if you're on Next.js 14 or later. If you're still on 13.0–13.2, install @vercel/og explicitly.
# Next.js 14+ — no extra install needed
# Next.js 13.0–13.2 only:
npm install @vercel/ogCreate an opengraph-image.tsx file inside any route segment. The App Router picks it up automatically and wires it to the correct meta tags — no <Head> juggling required. The file must export a default function and an optional size export for dimensions.
// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';
import { getBlogPost } from '@/lib/blog';
export const runtime = 'edge';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';
export default async function OgImage({
params,
}: {
params: { slug: string };
}) {
const post = await getBlogPost(params.slug);
return new ImageResponse(
(
<div
style={{
display: 'flex',
flexDirection: 'column',
justifyContent: 'flex-end',
width: '100%',
height: '100%',
background: 'linear-gradient(135deg, #0f0c29, #302b63, #24243e)',
padding: '60px',
}}
>
<p style={{ color: '#a78bfa', fontSize: 20, margin: 0 }}>
{post.category.toUpperCase()}
</p>
<h1
style={{
color: 'white',
fontSize: 64,
fontWeight: 700,
lineHeight: 1.1,
margin: '16px 0 24px',
}}
>
{post.title}
</h1>
<p style={{ color: '#94a3b8', fontSize: 24, margin: 0 }}>
empire-ui.com
</p>
</div>
),
{ ...size }
);
}One more thing — the export const runtime = 'edge' line is not optional if you want that sub-80ms response. Without it, the function runs in the Node.js runtime which adds a cold start penalty. Edge Runtime keeps the function in memory at Vercel's CDN edge globally.
Loading Custom Fonts: The Part Nobody Documents Clearly
The ImageResponse renderer is not a browser. It uses a custom Yoga-based layout engine with a bundled Satori renderer underneath. That means web fonts loaded via @font-face in your CSS don't work here — you have to pass font data as an ArrayBuffer explicitly through the fonts option.
The cleanest approach for Edge Runtime is fetching the font from a public URL at request time. Google Fonts exposes .ttf files directly — find the raw URL by inspecting the CSS file Google serves for any font family.
import { ImageResponse } from 'next/og';
export const runtime = 'edge';
async function loadFont(url: string): Promise<ArrayBuffer> {
const res = await fetch(url);
return res.arrayBuffer();
}
export default async function OgImage() {
const interBold = await loadFont(
'https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuFuYAZ9hiJ-Ek-_EeA.woff2'
);
return new ImageResponse(
<div style={{ fontFamily: 'Inter', display: 'flex' /* ... */ }}>
<h1 style={{ fontWeight: 700 }}>Hello from Edge</h1>
</div>,
{
width: 1200,
height: 630,
fonts: [
{
name: 'Inter',
data: interBold,
weight: 700,
style: 'normal',
},
],
}
);
}Honestly, the fetch-on-every-request approach works fine in production because Vercel's edge caches the font aggressively after the first hit — but if you want guaranteed zero latency for the font, store the .ttf file in your public/ directory and read it with the Node.js fs module instead. You can't use fs on the Edge Runtime though, so you'd need to drop back to Node for that pattern.
Quick aside: woff2 vs ttf — Satori actually accepts both, but .ttf is more reliably supported across font families. If a custom font renders as boxes or falls back to sans-serif, switch to .ttf first before debugging anything else.
CSS Subset and Layout Gotchas in ImageResponse
Satori supports a meaningful subset of CSS, not all of it. The big wins: flexbox (including gap, align-items, justify-content), background including gradients, border-radius, box-shadow, opacity, transform (translate/rotate/scale), and most text properties. What's missing: grid, position: sticky, overflow: scroll, pseudo-elements (:before, :after), calc(), CSS custom properties (var(--)), and backdrop-filter.
No backdrop-filter is the painful one if you're trying to replicate a glassmorphism look in your OG image. You can fake the glass effect with a semi-transparent background: rgba(255,255,255,0.1) over a gradient background and a light border — it reads well at 1200×630 without needing the actual blur. For inspiration on what glassmorphism looks like in pure CSS terms, the glassmorphism generator is handy for pulling the right background/opacity values.
All elements default to display: flex in Satori. If you write <div> without an explicit display: 'flex' in the style prop, the layout might not behave how you expect. Always be explicit about display mode. Line 1 of every container: display: 'flex'.
// ✅ Correct — explicit flex on every container
<div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
<span style={{ fontSize: 48, color: 'white' }}>Title here</span>
<span style={{ fontSize: 24, color: '#94a3b8' }}>Subtitle</span>
</div>
// ❌ Will behave unexpectedly — implicit display
<div style={{ flexDirection: 'column' }}>
<span>Title</span>
</div>Text wrapping is another gotcha. Long titles don't wrap automatically — you need flexWrap: 'wrap' on the container AND the text node needs width: '100%' or a defined maxWidth. For blog post titles especially, add a maxWidth: 900 on the <h1> to prevent overflow at the right edge.
Generating OG Images for Dynamic Routes at Scale
Static routes are trivial. Dynamic routes — blog posts, product pages, user profiles — are where the pattern gets interesting. The opengraph-image.tsx convention in App Router receives params just like a page component, so pulling post data is a single async call.
One thing to think about: you can generate OG images at build time using generateStaticParams. If your blog has 200 posts and you've already set up SSG for them, exporting generateStaticParams from opengraph-image.tsx will pre-render all 200 OG images at build time. That eliminates runtime latency entirely for those pages.
// Pre-render OG images at build time for all known slugs
export async function generateStaticParams() {
const posts = await getAllPosts();
return posts.map((post) => ({ slug: post.slug }));
}For truly dynamic content — user-generated pages, dashboards, anything that changes after deploy — stay on Edge Runtime and let Vercel's CDN cache the response. Set a Cache-Control header if you need to control how long the image stays stale. The default CDN TTL on Vercel for OG images is 5 minutes, which is fine for most content.
Look, the combination of generateStaticParams for known slugs + Edge Runtime fallback for unknown slugs is the production-grade setup. You get build-time performance for your evergreen content and dynamic generation for fresh content with no manual cache busting.
Designing OG Images That Actually Get Clicked
The technical setup is only half the job. An OG image that's visually boring is almost worse than no image — it signals low effort to whoever sees the share. A few design principles that work at 1200×630px.
First, think in zones. The left 60% is where the text lives. The right 40% can hold an illustration, screenshot, or just strong geometric shapes. Keep critical text away from the edges — 48px minimum padding on all sides — because some platforms crop OG images to 2:1 ratios. At 1200×630, you're already at 1.9:1, which is close enough that padding matters.
Font size hierarchy matters more here than on any webpage because the image renders at whatever size the platform decides. Twitter/X shows OG images at roughly 506×253px on desktop. That 64px title you set? It renders at about 26px effective size. Go bigger than feels comfortable — 72px for title, 28px for subtitle, 20px for metadata is a safe floor.
Color contrast. Pure white on dark gradients reads cleanest. If you're using a brand gradient like the gradient generator outputs, run it through a contrast checker at the darkest and lightest points before committing. You're optimizing for readability on a tiny thumbnail, not beauty at full size.
One pattern that works really well: a dark-gradient background with your brand color as an accent bar on the left edge (a 4px wide div at full height), article category in the accent color at 18px, title in white at 68px, and your domain name in gray at the bottom. Simple, branded, readable. Looks great as a thumbnail on every platform from LinkedIn to iMessage link previews.
Testing, Debugging, and Deploying OG Images
Preview your OG image locally by visiting http://localhost:3000/blog/your-slug/opengraph-image directly in the browser. The route serves the PNG directly, so you see exactly what social platforms will see. No need for a special tool during development.
For debugging layout issues, temporarily add border: '2px solid red' to the containers giving you trouble. Since everything's JSX, the dev loop is fast — change JSX, reload the URL, see the result. Much tighter than debugging a Puppeteer screenshot pipeline.
# After deploying, validate with meta tag debuggers:
# Twitter Card Validator: https://cards-dev.twitter.com/validator
# Facebook Sharing Debugger: https://developers.facebook.com/tools/debug/
# LinkedIn Post Inspector: https://www.linkedin.com/post-inspector/One last deployment thing: Vercel caches OG images at the CDN layer. If you push a design update and need to invalidate the cache immediately, you can append a ?v=2 query parameter to the metadataBase URL in your layout.tsx, or use Vercel's cache purge API. Otherwise, plan for up to 5 minutes of stale images in the wild after a deploy.
The page transition and routing work covered in page transitions in Next.js applies here too — if your pages use App Router transitions, the OG image route is isolated and unaffected, which is one less thing to worry about. That's the beauty of the file-based convention: the OG image is just another route that happens to return a PNG.
FAQ
No. Next.js 14 re-exports ImageResponse from next/og directly — no extra package needed. Only install @vercel/og separately if you're on Next.js 13.0 through 13.2.
Satori doesn't use browser font loading — you must pass font data as an ArrayBuffer via the fonts option in ImageResponse. Fetch a .ttf file from Google Fonts CDN and pass the result of .arrayBuffer() directly.
No to both. Satori supports flexbox only — no grid. backdrop-filter is also unsupported, but you can fake a glassmorphism look with a semi-transparent rgba() background over a gradient.
Vercel's CDN caches OG image routes automatically with a 5-minute TTL. For longer caching, return a Cache-Control: public, max-age=86400, stale-while-revalidate=604800 header from your ImageResponse function.