og-images-generator

OpenGraph Images Generator

Generate OG images from a static folder and / or a middleware.
Extract metadata from HTML pages. No headless browser involved. Comes as a CLI, API or plugins.

---

Table of Contents

• Installation
• Usage
  • CLI
  • Programmatic (JS API)
  • Express / Connect middleware
  • Rollup plugin
  • Vite plugin
  • Astro integration
• Notes on image optimization
• References

---

Installation

npm i og-images-generator

Create a og-images.config.js in your current workspace root.

See this og-images.example-config.js for a full working example. It's the config used in every demo.

The gist is:

// ./og-images.config.js

import { html, styled, OG_SIZE, FONTS } from 'og-images-generator';

const style1 = styled.div`
	display: flex;
`;

/** @type {import('og-images-generator').PathsOptions} */
export const paths = {
	// DEFAULTS:
	base: './dist',
	out: './dist/og',
	json: './dist/og/index.json',
};

/** @type {import('og-images-generator').Template} */
export const template = ({ page }) =>
	html` <!-- Contrived example -->
		<div style=${style1}>
			${page.meta?.tags['og:title']} - ${page.meta?.tags['og:description']}
		</div>`;

/** @type {import('og-images-generator').RenderOptions} */
export const renderOptions = {
	satori: { fonts: [await FONTS.sourceSans()], ...OG_SIZE },
};

You need to export renderOptions and template from your og-images-generator configuration file.

[!NOTE]
Helpers styled.div is a dummy strings concatenation literal (to get syntax highlighting).
div is the only needed (and available) tag, as it makes no difference anyway.

Also, you don't need to wrap interpolated HTML attributes with quotes (e.g. style="${foo}").
<foo-bar style=${styles.baz}></foo-bar> just works.

Usage

As a preamble, don't forget to add the appropriate meta for your OGs, there is plenty on ressources on the web on how to setup your SEO with your favorite environment.

---

By default:

• https://example.com/ gives https://example.com/og/index.png
• https://example.com/my-page/ gives https://example.com/og/my-page.png

[!WARNING]
/ → index.png is an exception.
We don't want https://example.com/og.png, as to keep this library output well segregated from the rest of your dist.
That's why so we need to disambiguate the root path.

For https://example.com:

<meta property="og:image" content="https://example.com/og/index.png" />

<meta property="og:image" content="https://example.com/og/nested/my-page.png" />

It's a contrived example. Fine-tuning SEO tags is an ancient, dark art.
You'll need the twitter: stuff and other massaging, but that's really out of the scope of this library, which does not mess with your HTML.

[!NOTE]
Additional ressources

• Demo projects
• API documentation

---

[!TIP]
Recommended VS Code extensions

• Styled Components for inline CSS highlighting: styled-components.vscode-styled-components
• HTML highlighting: bierner.lit-html

CLI

npx generate-og

# defaults to
npx generate-og --base dist --out dist/og --json dist/og/index.json

It will parse all the meta tags (in head) and JSON LDs script content (in head and body).

Programmatic (JS API)

import { generateOgImages } from 'og-images-generator/api';

await generateOgImages(/* options */);

Express / Connect middleware

import { connectOgImagesGenerator } from 'og-images-generator/connect';

app.use(await connectOgImagesGenerator(/* pathPrefix: string */));

Rollup plugin

import { rollupOgImagesGenerator } from 'og-images-generator/rollup';

/** @type {import('rollup').RollupOptions} */
export default {
	plugins: [
		//
		rollupOgImagesGenerator(),
	],
};

Vite plugin

import { defineConfig } from 'vite';
import { viteOgImagesGenerator } from 'og-images-generator/vite';

export default defineConfig({
	plugins: [
		//
		viteOgImagesGenerator(),
	],
	build: {
		rollupOptions: {
			input: {
				foo: 'pages/foo.html',
				bar: 'pages/bar.html',
			},
		},
	},
});

Astro integration

import { defineConfig } from 'astro/config';

import { astroOgImagesGenerator } from 'og-images-generator/astro';

export default defineConfig({
	integrations: [
		//
		astroOgImagesGenerator(),
	],
});

Notes on image optimization

You could use a CDN proxy to handle on the fly image optimizations.
Also AFAIK, all major social networks crawlers are transforming and caching assets themselves.
It's their job to normalize optimizations in order to serve assets to their users.

References

• vercel/satori
• natemoo-re/satori-html
• yisibl/resvg-js
• lit/ssr

---

Other projects 👀…

• retext-case-police: Check popular names casing. Example: ⚠️ github → ✅ GitHub.
• remark-lint-frontmatter-schema: Validate your Markdown frontmatter data against a JSON schema.
• JSON Schema Form Element: Effortless forms, with standards.

---

Find this project useful?

---

🔗  JulianCataldo.com