OG Image Generation on the Edge

A rough reference implementation is available on GitHub. You can deploy it to your own Cloudflare account in a few minutes if you want to try this approach yourself.

The Key Insight

Most OG image solutions work like this: you define your template separately, pass data to it, and get an image back. Satori wants JSX. Other services want you to use their template builder. The template always lives somewhere else.

This approach is different. The OG template is embedded directly in your deployed page as a hidden <template> element. Same HTML. Same CSS. Same Tailwind classes. Same fonts. When you want an OG image, a worker visits your actual page, extracts the template, and screenshots it.

This means there’s no template drift. When you update your design system, your OG images update automatically. No separate build step, no special syntax, no “OG-compatible” subset of CSS to learn.

Why Not Satori?

Satori is the popular choice for OG images, and for good reason. It’s fast and runs anywhere JavaScript does. Vercel’s @vercel/og is built on it, and it powers countless sites.

But Satori requires you to maintain a separate design system:

• Limited CSS support: no grid, limited flexbox, specific font handling
• JSX-to-SVG translation: your components need to be written with Satori’s subset in mind
• Font loading complexity: you need to bundle fonts or fetch them at runtime
• Separate templates: your OG designs live in a different place than your site’s actual pages

For simple text-on-gradient images, Satori is great. But I wanted to use WebGL shaders, the same Tailwind utilities, and the same fonts as the rest of my site. I didn’t want to maintain a parallel design system just for OG images.

What You Can Build

Because the screenshot captures a real browser, you can use anything that renders in Chrome: canvas graphics, CSS patterns, custom fonts, whatever. Here are some examples (click to open the full size image):

Preview Code

<OGTemplate>
  <GrainShaderOG client:load />
</OGTemplate>

// GrainShaderOG.tsx
<div className="w-[1200px] h-[630px] relative overflow-hidden">
  <GrainGradient
    colorBack="#042f2e"
    colors={["#0d9488", "#134e4a", "#115e59", "#0f766e"]}
    shape="wave"
    softness={0.8}
    intensity={0.4}
    noise={0.3}
    speed={0}
  />
  <div className="relative z-10 h-full p-16 flex flex-col justify-between text-white">
    <div>
      <p className="text-xl uppercase tracking-widest text-teal-400 mb-4">
        &lt;GrainGradient /&gt;
      </p>
      <h1 className="text-5xl font-mono tracking-tight leading-tight">
        Using Paper Shaders in React
      </h1>
    </div>
    <p className="text-2xl text-teal-200/70">mattrothenberg.com</p>
  </div>
</div>

Preview Code

<OGTemplate>
  <DitherShaderOG client:load />
</OGTemplate>

// DitherShaderOG.tsx
<div className="w-[1200px] h-[630px] relative overflow-hidden">
  <Dithering
    colorBack="#1c1917"
    colorFront="#0d9488"
    shape="swirl"
    type="4x4"
    size={4}
    speed={0}
  />
  <div className="absolute inset-0 bg-linear-to-b from-transparent to-black" />
  <div className="relative z-10 h-full p-16 flex flex-col justify-between text-white">
    <div>
      <p className="text-xl uppercase tracking-widest text-teal-400 mb-4">
        &lt;Dithering /&gt;
      </p>
      <h1 className="text-5xl font-mono tracking-tight leading-tight">
        Using Paper Shaders in React
      </h1>
    </div>
    <p className="text-2xl text-white uppercase">mattrothenberg.com</p>
  </div>
</div>

Preview Code

// SpheresOG.tsx — uses @react-three/fiber + @react-three/rapier
<Canvas camera={{ position: [0, 0, 30], fov: 17.5 }}>
  <Physics gravity={[0, 0, 0]}>
    {sphereConfigs.map((props, i) => (
      <Sphere key={i} {...props} />
    ))}
  </Physics>
  <Environment resolution={128}>
    <Lightformer form="circle" intensity={150} position={[0, 5, -9]} />
    <Lightformer form="ring" color="#6366f1" intensity={120} position={[10, 10, 0]} />
  </Environment>
  <EffectComposer>
    <Vignette darkness={0.4} offset={0.3} />
  </EffectComposer>
</Canvas>

// Spheres attract toward center with zero gravity
function Sphere({ color, ...props }) {
  useFrame(() => {
    api.current?.applyImpulse(
      vec.copy(api.current.translation()).negate().multiplyScalar(0.2)
    );
  });
  return (
    <RigidBody linearDamping={4} angularDamping={1} colliders={false}>
      <BallCollider args={[1]} />
      <mesh><sphereGeometry /><meshStandardMaterial color={color} /></mesh>
    </RigidBody>
  );
}

Preview Code

<OGTemplate>
  <div class="w-full h-full bg-white relative flex flex-col">
    <div
      class="h-32 w-full"
      style="background: repeating-linear-gradient(
        90deg, #000 0px, #000 3px, transparent 3px, transparent 12px
      );"
    />
    <div class="flex-1 flex flex-col items-center justify-center text-gray-900 px-16">
      <p class="text-2xl uppercase tracking-[0.3em] text-gray-500 mb-6">
        Hello my name is
      </p>
      <h1 class="text-7xl font-bold uppercase tracking-tight">
        Matt Rothenberg
      </h1>
    </div>
    <div
      class="h-32 w-full"
      style="background: repeating-linear-gradient(
        90deg, #000 0px, #000 3px, transparent 3px, transparent 12px
      );"
    />
  </div>
</OGTemplate>

These are live images served by the OG worker. The grain and dither examples use canvas to generate noise patterns, while the minimal example is pure CSS. All three use the same Tailwind utilities and fonts as the rest of the site.

How It Works

The system has four main pieces:

The Template Element

The key building block is HTML’s <template> element. Content inside a <template> is inert: it doesn’t render, scripts don’t execute, images don’t load. It’s just sitting there, waiting to be used.

Here’s the OGTemplate component:

---
interface Props {
  width?: number;
  height?: number;
}

const { width = 1200, height = 630 } = Astro.props;
---

<template
  data-og-template
  data-og-width={String(width)}
  data-og-height={String(height)}
>
  <div style={`width:${width}px;height:${height}px;overflow:hidden;`}>
    <slot />
  </div>
</template>

The data-og-* attributes tell the worker what dimensions to use. The slot receives your actual OG design — regular HTML and CSS that can use all your site’s styles.

Template Extraction

When the worker visits your page, it runs a script that extracts the template and replaces the page content:

// Runs in the browser context via page.evaluate()
(() => {
  const tpl = document.querySelector('template[data-og-template]');
  if (!tpl) return null;

  // Read dimensions from data attributes
  const width = parseInt(tpl.getAttribute('data-og-width') || '1200', 10);
  const height = parseInt(tpl.getAttribute('data-og-height') || '630', 10);

  // Replace body with template content
  document.body.innerHTML = '';
  document.body.style.cssText = `margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden;`;
  document.body.appendChild(tpl.content.cloneNode(true));

  return { width, height };
})()

This is the magic moment: the page transforms from your regular content into a perfectly-sized OG image canvas. The worker then resizes the viewport to match and takes a screenshot.

Wiring Up Meta Tags

To use the OG worker, you point your og:image meta tag at the worker URL, passing your page URL as a parameter:

<meta
  property="og:image"
  content="https://og.mattrothenberg.com/?url=https://mattrothenberg.com/notes/edge-og-images"
/>

When a social platform fetches this URL, the worker screenshots your page’s template and returns the image. In Astro, I use a helper component to generate this URL:

---
// OGMeta.astro
interface Props {
  worker: string;  // https://og.mattrothenberg.com
  site: string;    // https://mattrothenberg.com
  path?: string;   // /notes/my-post
}

const { worker, site, path = Astro.url.pathname } = Astro.props;
const ogUrl = `${worker}/?url=${encodeURIComponent(site + path)}`;
---

<meta property="og:image" content={ogUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:image" content={ogUrl} />

The Screenshot Flow

Here’s the complete request flow through the worker:

The browser rendering step uses Cloudflare’s Browser Rendering API, which gives you a Puppeteer-compatible interface to a headless Chrome instance running on their edge network.

A naive implementation launches a fresh browser for every screenshot, then closes it. This works, but it’s wasteful — launching a browser is the expensive part, and concurrent requests for the same image would each spin up their own browser.

The solution is a Durable Object (OGRenderer) that holds a persistent browser instance and reuses it across requests. The worker routes screenshot requests to a singleton DO:

// In the worker's fetch handler
const id = env.OG_RENDERER.idFromName("singleton");
const stub = env.OG_RENDERER.get(id);
const doRes = await stub.fetch(doUrl.toString());

The DO does three things on top of the core screenshot logic:

1. Browser reuse — getBrowser() returns the existing browser if it’s still alive, or launches a new one if not. No more cold start per request.
2. Request deduplication — concurrent requests for the same cache key await the same in-flight Promise instead of each taking their own screenshot.
3. Failure cooldown — if a screenshot fails, that cache key gets a 60-second cooldown to prevent retry storms from burning through Browser Rendering quota.

The generate() method contains the actual screenshotting logic. It creates a new page (cheap) rather than a new browser (expensive):

private async generate({ url }: { url: string }): Promise<ArrayBuffer> {
  const browser = await this.getBrowser();
  const page = await browser.newPage();

  try {
    await page.setViewport({ width: 1200, height: 630, deviceScaleFactor: 2 });
    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 });

    // Extract and render the template
    const dimensions = await page.evaluate(OG_TEMPLATE_EXTRACT_SCRIPT);
    if (!dimensions) throw new Error(`No OG template found on page: ${url}`);

    await page.setViewport({
      width: dimensions.width,
      height: dimensions.height,
      deviceScaleFactor: 1,
    });

    // Wait for the component to signal it's done rendering
    await this.waitForReady(page);

    const screenshot = await page.screenshot();
    return screenshot;
  } finally {
    await page.close(); // Close the page, not the browser
  }
}

Note the finally block closes the page, not the browser. The browser stays alive for the next request.

Readiness Signal

The original implementation waited a fixed number of requestAnimationFrame callbacks before taking the screenshot — essentially “wait N frames and hope everything has rendered.” Too few frames and heavy WebGL scenes would get captured mid-render; too many and simple templates would waste time.

Components now explicitly signal when they’re done rendering by setting window.__OG_READY__ = true. The screenshotter polls for this signal:

private async waitForReady(page: Page): Promise<void> {
  try {
    await page.waitForFunction('window.__OG_READY__ === true', { timeout: 25000 });
  } catch {
    // Signal never set — fall back to 10-frame RAF wait for simple templates
    await page.evaluate(`new Promise(resolve => {
      let f = 0;
      const w = () => { f++; f < 10 ? requestAnimationFrame(w) : resolve(); };
      requestAnimationFrame(w);
    })`);
  }
}

For Three.js scenes that need many frames before they’re fully rendered, a ReadinessSignal component uses useFrame to count 30 rendered frames before signaling:

function ReadinessSignal() {
  const frameCount = useRef(0);
  const signaled = useRef(false);

  useFrame(() => {
    if (signaled.current) return;
    frameCount.current++;
    if (frameCount.current >= 30) {
      signaled.current = true;
      (window as any).__OG_READY__ = true;
    }
  });

  return null;
}

Simpler components that render synchronously can signal immediately in a useEffect:

useEffect(() => {
  (window as any).__OG_READY__ = true;
}, []);

Caching & Performance

The caching strategy is what makes this viable:

Tier 1: Edge Cache (Cache API)

• Stored at Cloudflare’s edge locations
• Sub-millisecond reads for repeat requests

Tier 2: R2 Storage

• Persistent object storage
• Survives edge cache evictions
• Automatically backfills the edge cache on read

async function getFromCache({ env, key, requestUrl, options }) {
  // 1. Try edge cache first (fastest)
  const cache = caches.default;
  const cacheRequest = new Request(new URL(`/cache/${key}`, requestUrl));
  const cached = await cache.match(cacheRequest);
  if (cached) return cached;

  // 2. Try R2 (persistent)
  const r2Object = await env.OG_CACHE.get(key);
  if (r2Object) {
    const response = new Response(r2Object.body, {
      headers: {
        "Content-Type": "image/png",
        "Cache-Control": `public, max-age=${cacheTtl}`,
      },
    });

    // Backfill edge cache (non-blocking)
    cache.put(cacheRequest, response.clone()).catch(() => {});

    return response;
  }

  return null; // Cache miss, need to generate
}

The cache key is a SHA-256 hash of just the URL — one URL always maps to exactly one cached image. Is the tradeoff worth it? For me, yes. I value design flexibility over raw generation speed, and the caching makes the slowness invisible in normal use.

Security & Admin

Locking Down the Screenshotter

First, there’s an ALLOWED_ORIGINS list. The worker checks the target URL’s origin against a configured allowlist before doing anything else. If the domain isn’t on the list, the request is rejected immediately. No screenshot, no cache lookup, nothing.

Second, target URLs are normalized to just the origin and pathname. Query parameters get stripped entirely, which prevents attackers from busting the cache by appending random strings to otherwise-identical URLs. If you need to regenerate an image (say, after a design change), that happens through the admin UI’s purge functionality, not through URL manipulation.

Third, before spinning up a Browser Rendering session, the worker does a cheap preflight fetch of the target URL. If the page doesn’t return a 200 or the HTML doesn’t contain a data-og-template attribute, the request bails out immediately. This keeps the expensive part — launching a headless browser — behind a lightweight validation step that costs almost nothing.

Admin UI

To manage the cache, I built a small admin interface that shows all cached images with their metadata. You can browse, inspect, and purge images without touching the R2 console:

cf-ogpurge all

Cached

3

Size

396 KB

1200×630/142 KB/2h

delete

1200×630/98 KB/5h

delete

1200×630/156 KB/1d

delete

Admin UI for browsing and managing cached OG images

The admin UI is a React SPA bundled into a single HTML file that the worker serves at /admin. It uses the same R2 bucket listing API that you’d use in a dashboard, wrapped in a minimal interface.

Protecting the Admin with Cloudflare Access

Instead of building auth into the worker, I used Cloudflare Access to handle it at the edge.

Access enforces authentication before requests even reach your worker, so the worker stays focused on its actual job.

Local Development

For development, you don’t want to wait for the worker to screenshot every change. The OGTemplate component includes an inline script that activates when you add ?og-preview to any URL:

if (new URLSearchParams(location.search).has('og-preview')) {
  document.addEventListener('DOMContentLoaded', function() {
    var tpl = document.querySelector('template[data-og-template]');
    if (tpl) {
      var w = parseInt(tpl.getAttribute('data-og-width') || '1200', 10);
      var h = parseInt(tpl.getAttribute('data-og-height') || '630', 10);
      document.body.innerHTML = '';
      document.body.style.cssText = `margin:0;padding:0;width:${w}px;height:${h}px;overflow:hidden;`;
      document.body.appendChild(tpl.content.cloneNode(true));
    }
  });
}

Visit localhost:4321/blog/my-post?og-preview and you see exactly what the OG image will look like. Instant feedback, no deploy required.

The Result

The tradeoffs are real: cold starts are slow, and you need Cloudflare’s Browser Rendering (which has usage limits and costs). But for a personal site where most images are cached and design flexibility matters, it’s been the right choice.