og-images-generator

og-images-generator is an open-source Node.js tool that generates Open Graph social sharing thumbnails from plain HTML and CSS templates, without a headless browser, by converting HTML to SVG and then to PNG.

What is og-images-generator?

og-images-generator is an open-source Node.js utility that creates Open Graph (social sharing) thumbnail images for websites from plain HTML and CSS templates. It accepts metadata extracted from pages—parsing all meta tags in the head and JSON-LD script tags in head and body—and outputs PNG images sized for social media cards. The tool runs in Node.js environments and is developed by Julian Cataldo, published on npm under the package name og-images-generator with an ISC license. It integrates with Astro, Express, Rollup, Vite, and Web Dev Server via plugins, and also offers a CLI and a programmatic API.

Key Features

• No headless browser — Converts HTML/CSS to SVG using Vercel's Satori, then to PNG with resvg-js; omits Puppeteer/Chromium so cold boot is fast and bundle size stays small.
• Metadata crawling — Scans the head for all meta tags and JSON-LD blocks, exposing them as page.meta and page.url for use in your image template, so existing SEO tags can drive the card content.
• Multiple integration points — Ships as a CLI (npx generate-og), a JS API (og-images-generator/api), an Express/Connect middleware, and plugins for Rollup, Vite, Web Dev Server, and an Astro integration.
• Hot module replacement (HMR) — When used with Vite or Astro plugins, editing your template triggers automatic regeneration and a browser refresh while you preview the image in an HTML document.
• Template authoring helpers — Provides styled.div and html template literal tags for syntax highlighting and formatting, with interpolation of HTML attributes without quoting.
• Per-route template branching — The root template receives page.url plus metadata, allowing conditional logic to render different card designs for different pages.
• Full output customization — renderOptions accepts Satori options (e.g., custom fonts via helpers like FONTS.sourceSans(), and size via OG_SIZE), exposing all underlying APIs for fine-tuned output.
• Known-issue documentation — The project documents real limitations: emojis are not supported with Satori's graphemeImages option, and Lit SSR encodes HTML entities that Satori doesn't decode (og-images-generator decodes the final template itself).

Who is it for?

• Web developers building static or server-rendered sites — Generate consistent, branded Open Graph images automatically from existing page metadata without maintaining a manual design per page.
• Astro users — The Astro integration plugs into the config, and you can also leverage Astro server endpoints with the JS API and Content Collections to generate images dynamically.
• Jamstack and SSG users — Use the Rollup or Vite plugin during build to generate a set of static PNGs into the output folder (defaults to dist/og).
• Express/Connect API users — Mount the middleware to create on-the-fly OG images from page metadata, useful for dynamic pages.

What can you do with og-images-generator?

• Set up automated social cards for a multi-page site — Drop the config file, define one template, and every page in dist gets a dist/og/<page>.png matching its route.
• Design typographic posters with flexbox and gradients — Because the HTML/CSS is rendered by Satori, you can use flex layouts, inline SVGs, borders, and gradients—all computed in SVG.
• Generate images on demand in a serverless function — Use the programmatic renderOgImage API to produce a PNG from any route when a crawler or social media bot requests it.
• Preview your card while you edit — With Vite or Astro HMR, your browser refreshes automatically as you tweak the template, accelerating iteration.

How does og-images-generator work?

The tool crawls your built HTML (either from a folder like dist or via middleware at runtime), parses <meta> tags and JSON-LD scripts, and passes them to your custom template. That template—an HTML string with inline styles—is fed to Satori, which converts it to an SVG while preserving layout and typography calculations. Finally, resvg-js rasterizes the SVG to a PNG at the configured size (e.g., OG_SIZE), and the files land in the output directory.

Pros and cons

Pros:

• No headless browser means lower memory and faster cold starts than Puppeteer-based generators.
• Integrates with popular build tools and frameworks through official plugins.
• Lets you author cards with the full power of HTML/CSS instead of a closed UI or canvas API.

Cons:

• Emojis fail when the Satori graphemeImages option is used; the README suggests stripping them with a library like emoji-strip.
• Rich-text styling from external HTML snippets is limited; the author recommends keeping titles and descriptions as plain text with \n and \t line breaks.

Pricing

og-images-generator is free and open-source, released under the ISC license. It is available on npm for installation without any fee.

FAQ

Is og-images-generator free?

Yes, it is open-source under the ISC license and available on npm for free.

Does og-images-generator require a headless browser?

No, it converts HTML/CSS to SVG via Satori and then to PNG with resvg-js, so there's no Puppeteer or Chromium dependency.

What integrations are available?

It offers a CLI, a JavaScript API, an Express/Connect middleware, and plugins for Rollup, Vite, Web Dev Server, and Astro.

How do I set up per-page templates?

You branch on page.url inside a single root template, or import separate partial templates; the tool passes page metadata alongside the URL.

Why are emojis not showing in my generated images?

A known issue: emojis don't work with Satori's graphemeImages option; the workaround is to strip emojis from text with a library like emoji-strip.