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
How It Works
Section titled “How It Works”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:
- Edge cache (Cache API) — Returns the image from the colo-local edge cache if present (fastest, no KV read)
- KV cache — On an edge miss, returns the screenshot from KV (durable, cross-colo) and warms the edge cache
- Checks and renders the page — On a full miss, checks the page exists, then uses Cloudflare Browser Rendering
- Takes screenshot — Captures the page at
VIEWPORT(default 1200×630) - Populates both caches — Stores in KV and in the edge cache for
CACHE_TTL_SECONDS(default 7 days) - Returns PNG — Serves the image with proper headers
Prerequisites
Section titled “Prerequisites”- Cloudflare Workers account; see Browser Run limits
wranglerCLI installed
1. Create KV Namespace
Section titled “1. Create KV Namespace”cd og-screenshot-workernpx wrangler kv namespace create CACHECopy the returned id into wrangler.toml.
2. Configure the Site
Section titled “2. Configure the Site”Set SITE_ORIGIN, the route, and any optional variables in wrangler.toml
(see Configuration).
3. Deploy Worker
Section titled “3. Deploy Worker”npm installnpx wrangler deployFor local development:
npx wrangler devWrangler 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.
4. Add DNS Record
Section titled “4. Add DNS Record”In Cloudflare Dashboard → DNS → Add record:
| Type | Name | Content | Proxy |
|---|---|---|---|
| AAAA | og | 100:: | Proxied |
This routes og.example.com to the worker.
5. Update Head Component
Section titled “5. Update Head Component”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" />Configuration
Section titled “Configuration”wrangler.toml
Section titled “wrangler.toml”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"Bindings
Section titled “Bindings”| 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.
Variables
Section titled “Variables”| 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).
Multiple Sites
Section titled “Multiple Sites”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" }]npx wrangler deploy --env docsKV keys are scoped by site host (og:{host}:{slug}), so installs can share
one KV namespace safely.
Source Layout
Section titled “Source Layout”| 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 |
URL Format
Section titled “URL Format”https://og.example.com/{slug}.pngExamples
Section titled “Examples”| 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 |
Cache Headers
Section titled “Cache Headers”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.
Testing
Section titled “Testing”# Check if workingcurl -I https://og.example.com/about.png
# Verify cache hit on second requestcurl -I https://og.example.com/about.png | grep -i X-CacheCache Warmup
Section titled “Cache Warmup”The worker warms its own cache from the site’s sitemap on a Cron Trigger
([triggers] crons in wrangler.toml, weekly by default):
- Fetches
SITEMAP_URL(a sitemap index is followed one level deep) - Maps each page URL on
SITE_ORIGINto a Slug usingPAGE_PATH - Skips Slugs already in KV; renders and stores the rest, up to
WARMUP_LIMITper 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:
npx wrangler dev --test-scheduledcurl "http://localhost:8787/__scheduled?cron=0+6+*+*+SUN"Fallback Behavior
Section titled “Fallback Behavior”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.
Contributor Notes
Section titled “Contributor Notes”Implementation Contract
Section titled “Implementation Contract”The worker is easiest to maintain when these boundaries are kept explicit:
- Slug parsing and validation
- Cache lookup order (Edge, then KV)
- Rendering on full miss only
- Fallback fetch if rendering fails
If you refactor, preserve this order to avoid hidden cost increases in Browser Rendering usage.
Development
Section titled “Development”npm test # vitest, in-memory KV and Edge Cache adaptersnpm run typecheckSafe Refactor Checklist
Section titled “Safe Refactor Checklist”- Keep
X-Cachesemantics 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
Cost Considerations
Section titled “Cost Considerations”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.
AI Contribution Attribution
Section titled “AI Contribution Attribution”Assisted-by: GitHub Copilot:GPT-5.3-Codex Assisted-by: Copilot SDK:gpt-6-luna Assisted-by: Copilot SDK:gpt-6.1-terra
📦 Source: soderlind/og-screenshot-worker · Edit on GitHub