Skip to content
New site — Virtual Media Folders now has its own home.Visit vmf.soderlind.no →

OG Screenshot Worker

Generate dynamic Open Graph images using Cloudflare Browser Rendering.

This Cloudflare Worker takes live screenshots of pages on one site and serves them as OG images for social media previews.

The worker is standalone: one install per site. Every site-specific value lives in wrangler.toml, so you can deploy it N times (one per site) without touching the code. Cache Warmup runs inside the worker on a Cron Trigger, so no CI is needed either.

How It Works · Setup · Configuration · Usage · Cache Warmup


When someone shares a link to example.com/plugins/wp-loupe/, social platforms fetch https://og.example.com/plugins/wp-loupe.png. The worker caches on two tiers and only renders on a full miss:

  1. Edge cache (Cache API) — Returns the image from the colo-local edge cache if present (fastest, no KV read)
  2. KV cache — On an edge miss, returns the screenshot from KV (durable, cross-colo) and warms the edge cache
  3. Checks and renders the page — On a full miss, checks the page exists, then uses Cloudflare Browser Rendering
  4. Takes screenshot — Captures the page at VIEWPORT (default 1200×630)
  5. Populates both caches — Stores in KV and in the edge cache for CACHE_TTL_SECONDS (default 7 days)
  6. Returns PNG — Serves the image with proper headers

Terminal window
cd og-screenshot-worker
npx wrangler kv namespace create CACHE

Copy the returned id into wrangler.toml.

Set SITE_ORIGIN, the route, and any optional variables in wrangler.toml (see Configuration).

Terminal window
npm install
npx wrangler deploy

For local development:

Terminal window
npx wrangler dev

Wrangler 4.143.0 does not emulate Quick Actions locally. To test screenshots with that version, temporarily add remote = true to [browser] in wrangler.toml; the KV binding remains local. Remote Browser Run usage is charged to your account.

In Cloudflare Dashboard → DNS → Add record:

Type Name Content Proxy
AAAA og 100:: Proxied

This routes og.example.com to the worker.

In your Astro site, set the og:image URL:

---
const ogSlug = Astro.locals.starlightRoute?.id || slug || 'index';
const ogImage = `https://og.example.com/${ogSlug}.png`;
---
<meta property="og:image" content={ogImage} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

name = "og-screenshot"
main = "src/index.ts"
compatibility_date = "2026-03-24"
compatibility_flags = ["nodejs_compat"]
[vars]
SITE_ORIGIN = "https://example.com"
PAGE_PATH = "/{slug}/"
FALLBACK_PATH = "/og/{slug}.png"
[browser]
binding = "BROWSER"
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"
[triggers]
crons = ["0 6 * * SUN"]
[[routes]]
pattern = "og.example.com/*"
zone_name = "example.com"
Binding Type Description
BROWSER Browser Cloudflare Browser Rendering binding
CACHE KV Namespace Screenshot cache storage

On-demand screenshots use the Browser Run snapshot Quick Action, which provides the page status with the screenshot and requires a compatibility date of 2026-03-24 or later. The response also includes HTML, which the worker discards. Cache Warmup continues to reuse a Puppeteer browser session.

The equivalent cloudflare.config.ts must be kept in sync with wrangler.toml when changing site variables, bindings, routes, or the warmup schedule.

Variable Default Description
SITE_ORIGIN — (required) Site to screenshot, e.g. https://example.com
PAGE_PATH /{slug}/ Slug → page path. index always maps to /
FALLBACK_PATH unset Fallback Image path, e.g. /og/{slug}.png. Unset returns 502 on failure
SITEMAP_URL SITE_ORIGIN/sitemap.xml Sitemap or sitemap index used by Cache Warmup
VIEWPORT 1200x630 Screenshot size
CACHE_TTL_SECONDS 604800 Screenshot lifetime across KV Cache and Edge Cache (min 60)
BROWSER_MAX_AGE_SECONDS 86400 max-age sent to browsers and crawlers
WARMUP_LIMIT 50 Max renders per Cache Warmup run

Invalid configuration is rejected on the first request (HTTP 500 plus a log line naming the bad variable).

Deploy one worker per site. Either copy wrangler.toml per site, or use Wrangler environments:

[env.docs]
name = "og-screenshot-docs"
vars = { SITE_ORIGIN = "https://docs.example.com" }
kv_namespaces = [{ binding = "CACHE", id = "..." }]
browser = { binding = "BROWSER" }
triggers = { crons = ["0 6 * * SUN"] }
routes = [{ pattern = "og.docs.example.com/*", zone_name = "example.com" }]
Terminal window
npx wrangler deploy --env docs

KV keys are scoped by site host (og:{host}:{slug}), so installs can share one KV namespace safely.

Module Responsibility
src/site-profile.ts Reads and validates per-install config; owns Slug ↔ URL mapping and Fallback Image URL
src/screenshot-store.ts Edge Cache → KV Cache lookup, write-back, keys, TTLs, X-Cache
src/render.ts Browser Rendering screenshot of one Slug
src/page-check.ts Pre-render check and browser response status validation
src/warmup.ts Sitemap → Slugs, renders cache misses
src/index.ts fetch and scheduled handlers wiring the modules

https://og.example.com/{slug}.png
Page OG Image URL
Homepage https://og.example.com/index.png
About https://og.example.com/about.png
WP Loupe https://og.example.com/plugins/wp-loupe.png
AI Router https://og.example.com/ai/ai-router.png
  • X-Cache: HIT-EDGE — Served from the local Cloudflare edge cache (fastest path).
  • X-Cache: HIT-KV — Served from Workers KV after an edge miss, then written back to edge cache.
  • X-Cache: MISS — Fresh screenshot generated, then written to both KV and edge cache.
Terminal window
# Check if working
curl -I https://og.example.com/about.png
# Verify cache hit on second request
curl -I https://og.example.com/about.png | grep -i X-Cache

The worker warms its own cache from the site’s sitemap on a Cron Trigger ([triggers] crons in wrangler.toml, weekly by default):

  1. Fetches SITEMAP_URL (a sitemap index is followed one level deep)
  2. Maps each page URL on SITE_ORIGIN to a Slug using PAGE_PATH
  3. Skips Slugs already in KV; renders and stores the rest, up to WARMUP_LIMIT per run, reusing one browser session

Warmup fills the KV Cache only. The Edge Cache fills on the first request in each colo.

Trigger it locally:

Terminal window
npx wrangler dev --test-scheduled
curl "http://localhost:8787/__scheduled?cron=0+6+*+*+SUN"

If the screenshot fails (timeout, browser error), the worker proxies the static image at FALLBACK_PATH on the site (for example a Satori-generated /og/{slug}.png). Fallback responses are never cached. Without FALLBACK_PATH, the worker returns 502.

Pages that don’t exist are never rendered when the pre-check detects them. The worker sends a HEAD request to the page (or GET if HEAD is not supported) and returns 404, cached for 5 minutes, if the site responds 404 or 410. The same applies if the browser subsequently receives either status; other browser navigation errors use the fallback.


The worker is easiest to maintain when these boundaries are kept explicit:

  1. Slug parsing and validation
  2. Cache lookup order (Edge, then KV)
  3. Rendering on full miss only
  4. Fallback fetch if rendering fails

If you refactor, preserve this order to avoid hidden cost increases in Browser Rendering usage.

Terminal window
npm test # vitest, in-memory KV and Edge Cache adapters
npm run typecheck
  • Keep X-Cache semantics accurate (HIT-EDGE, HIT-KV, MISS)
  • Ensure browser instances are closed in success and failure paths
  • Avoid changing cache key format without a migration strategy
  • Keep site-specific values in the Site Profile, never as constants

Quick Actions are billed for browser time. Cache Warmup uses Browser Sessions, which are billed for browser time and concurrent browsers. See the current Browser Run pricing.


Assisted-by: GitHub Copilot:GPT-5.3-Codex Assisted-by: Copilot SDK:gpt-6-luna Assisted-by: Copilot SDK:gpt-6.1-terra