og-engine 🖼️

The high-performance, platform-agnostic social image engine.
Build, preview, and deploy social images that look handcrafted—at the speed of the edge.

---

✨ What is it?

og-engine is an open-source framework for generating dynamic social meta tags and Open Graph images. Unlike generic generators, it focuses on premium typography, flexible templates, and zero-dependency SDKs.

• 🚀 Edge-Ready: Optimized for Cloudflare Workers, Vercel Edge, and Node.js.
• 🎨 Satori Powered: Uses JSX-to-SVG for high-fidelity rendering.
• 🛠️ Fully Typed: 100% TypeScript with generated schemas for every template.
• 📦 Zero-Dep SDK: A 2kB SDK to build complex URLs in your frontend.

---

⚙️ How it Works

og-engine decouples the design (templates) from the infrastructure (adapters).

graph TD
    A[Frontend/SDK] -- Request with Params --> B[Adapter Handler]
    B -- Validation --> C[Core Engine]
    C -- Component Metadata --> D[Template Registry]
    D -- JSX Element --> C
    C -- Satori --> E[SVG]
    E -- Resvg --> F[PNG/JPEG]
    F -- Cache & Stream --> B
    B -- Response --> A

Loading

The 3 Pillars:

1. Templates: Pure JSX components paired with a JSON schema. Templates are now flattened into single files for maximum portability.
2. Core: The central processing unit. It coordinates parameter coercion, font loading, SVG generation (via Satori), and final image encoding.
3. Adapters: Lightweight abstractions that bridge the Core to specific environments like Cloudflare R2/KV or Node.js.

---

🚀 Quick Start

Generate a stunning social image with a simple GET request:

# Get a sunset-themed OG image
curl "https://og.yourdomain.com/api/og?template=sunset&title=Hello+World" --output og.png

Local testing (editor + API on localhost:3000)

pnpm install
pnpm dev

Explicit (same result):

pnpm --filter @og-engine/web dev

Open:

• http://localhost:3000 (template editor)
• http://localhost:3000/api/og?template=sunset&size=og&title=Hello+World (direct image render)

Or using the SDK in your app:

import { buildOgUrl } from '@og-engine/sdk';

const url = buildOgUrl({
  baseUrl: 'https://og.yourdomain.com',
  template: 'sunset',
  size: 'twitter-og',
  format: 'png',
  params: {
    title: 'Designing at the Edge',
    author: '@saurabhsharma2u'
  }
});

---

📐 Platform Sizes

Platform	Size	Ratio
Twitter / X	1200 × 628	1.91:1
Instagram Post	1080 × 1080	1:1
LinkedIn	1200 × 627	1.91:1
Discord	1280 × 640	2:1
Generic OG	1200 × 630	1.91:1

---

🏠 Self-Hosting

The engine can be run with the local Node editor app (web) or integrated into existing Node/Cloudflare environments using adapters.

pnpm install
pnpm dev

---

📦 Packages

Package	Description	Version
@og-engine/sdk	Zero-dependency URL builder
@og-engine/core	Shared rendering logic
@og-engine/types	Shared TS types
@og-engine/adapter-node	Node.js adapter
@og-engine/adapter-cloudflare	Cloudflare adapter

---

🤝 Contributing

We love new templates! Please see CONTRIBUTING.md for the guide on how to build and submit your own designs.

📄 License

MIT © og-engine