Next.js OG Image Generator

Generates brand-consistent Open Graph images for Next.js projects by inferring design identity from existing project files, producing HTML layouts at 1200x630, converting them to PNG via the html2png.dev API, and wiring up the resulting metadata in the appropriate router format.

Supports:

• Next.js App Router
• Next.js Pages Router

When to Use

Activate this skill when the user asks to:

• Generate or batch-generate OG images or social preview images for a Next.js project
• Add og:image or twitter:image metadata to one or more pages
• Create branded Open Graph assets aligned with an existing design system
• Audit which pages are missing social preview images

Do not use this skill for:

• Non-Next.js projects
• Dynamic OG images rendered at request time (e.g., @vercel/og / ImageResponse)
• Animated or video-based social previews

Phase 1 — Infer Brand Identity

Before generating any image, inspect the following project files in order:

1. tailwind.config.* — color palette, font families, custom theme tokens
2. app/globals.css or styles/globals.css — CSS custom properties, base typography
3. styles/ directory — any additional stylesheets
4. components/ directory — sample components for visual density cues
5. docs/design-system.md — explicit design system documentation, if present
6. public/og-images/ — any existing OG images for visual reference

From these sources, infer the following properties:

Fallback defaults when no design system is found:

• Background: #ffffff
• Text: #0a0a0a
• Font: Inter via Google Fonts CDN
• Layout: centered, minimal, high-contrast

Phase 2 — Discover Routes

Identify all static routes that need OG images.

App Router:

find app -type f \( -name "page.tsx" -o -name "page.ts" -o -name "page.jsx" -o -name "page.js" \)

Pages Router:

find pages -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.ts" -o -name "*.js" \)

Skip the following:

• api/ routes
• Dynamic segments: [slug], [id], [...params], etc.
• Special files: _app, _document, 404, 500, error, loading, not-found

Derive the slug from the file path:

Phase 3 — Identify Missing OG Images

For each route slug, check whether a PNG already exists at:

public/og-images/<slug>.png

List all slugs that are missing an OG image and confirm with the user before proceeding with generation.

Phase 4 — Generate HTML Template (1200x630)

For each missing slug, create a self-contained HTML file that renders the OG image layout.

Constraints:

• Fixed viewport: 1200px x 630px — set on the root element, not via <meta viewport>
• Prefer Tailwind CDN for layout and utility classes; supplement with a <style> block for brand-specific values
• Fonts must be loaded via a <link> tag pointing to a CDN (see CDN Resources below)
• Typography sizing: headline 60–80px, subheadline 24–32px — both must remain legible at thumbnail size
• Avoid: CSS filter, backdrop-filter, glow effects, glitch animations, excessive radial gradients
• Respect the inferred color palette, font family, visual density, and brand tone

CDN Resources:

Tailwind (utility classes, no build step):

<script src="https://cdn.tailwindcss.com"></script>

Fonts (swap for the project's inferred typeface):

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap" rel="stylesheet">

Icons (Lucide — optional, for decorative elements):

<script src="https://unpkg.com/lucide@latest"></script>

Save each file to:

keep/og-images/<slug>.html

Phase 5 — Convert HTML to PNG

Send the HTML file to the html2png.dev API:

curl -s -X POST \
  "https://html2png.dev/api/convert?width=1200&height=630&format=png&deviceScaleFactor=2&delay=1000" \
  -H "Content-Type: text/html" \
  --data-binary @keep/og-images/<slug>.html

The API returns a JSON response. Extract the url field — this is the temporary PNG URL used in the next phase.

Note: the html2png.dev free tier is limited to 50 requests per hour per IP. When generating images for many routes in a single session, batch them or space requests accordingly.

Phase 6 — Download and Save PNG

mkdir -p public/og-images
curl -L -o public/og-images/<slug>.png "<url-from-phase-5>"

Phase 7 — Wire Up Metadata in Next.js

App Router — add to app/<route>/page.tsx or the nearest layout.tsx:

export const metadata = {
  openGraph: {
    images: [{ url: "/og-images/<slug>.png", width: 1200, height: 630 }],
  },
  twitter: {
    card: "summary_large_image",
    images: ["/og-images/<slug>.png"],
  },
};

Pages Router — add inside the component's <Head>:

import Head from "next/head";

// Inside your component:
<Head>
  <meta property="og:image" content="/og-images/<slug>.png" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:image" content="/og-images/<slug>.png" />
</Head>

Output File Structure

project/
├── keep/
│   └── og-images/
│       └── <slug>.html       # HTML source — commit for reproducibility
├── public/
│   └── og-images/
│       └── <slug>.png        # Generated PNG — served as a static asset

Completion Report

After each image is generated, report the following:

Remind the user to verify that the metadata export (App Router) or <Head> tags (Pages Router) are present in every relevant page file.

Common Failure Modes

html2png.dev returns an error

• Confirm the HTML is valid and self-contained
• Ensure font @import URLs are reachable from a public server
• Remove any localhost or relative asset references

PNG renders blank or misaligned

• Verify the root element has width: 1200px; height: 630px set explicitly
• Check that no ancestor element uses overflow: hidden in a way that clips content

Fonts not rendering correctly

• Confirm delay=1000 is present in the API URL — this gives the browser time to load web fonts before capture
• Add font-display: swap to any @font-face declarations
• Include a system font stack as a fallback (-apple-system, BlinkMacSystemFont, sans-serif)

OG image not appearing on social platforms

• Confirm the image URL is publicly accessible without authentication
• In production, use an absolute URL (https://yourdomain.com/og-images/<slug>.png) for og:image
• Use the Open Graph Debugger or Twitter Card Validator to flush platform caches