DEV Community: Stevie g

Open Graph images for Eleventy without paying the build-time tax

Stevie g — Fri, 24 Jul 2026 14:04:49 +0000

Share a link with no og:image and you get the dead gray card. On X, in Slack,
in Discord, your post sits next to ones with real preview images and loses. So
you decide to generate one per post. Reasonable. Then you look at how Eleventy
sites usually do it.

The two standard approaches, and what they cost

Approach one: render at build time with Satori (this is what most
eleventy-plugin-og-* packages do). Satori is fast and doesn't need a browser,
but it renders a subset of CSS, not real CSS. Flexbox mostly works; plenty of
other things don't. You also now own a font pipeline: font files checked into
the repo or downloaded in CI, emoji handled separately.

Approach two: render at build time with headless Chrome. Real CSS now, but
you've put Chromium inside your build. That means installing it in CI on every
run, roughly a hundred milliseconds to a few seconds per page, and a new way
for deploys to fail that has nothing to do with your content. A 500-post site
renders 500 images every full rebuild, including the 490 posts nobody will
share this year.

Both approaches share an assumption I stopped believing: that the image has to
exist when the build finishes.

The pattern: sign now, render on first share

An og:image has one consumer: social crawlers. Nothing fetches that URL until
the page is shared. So the image doesn't need to exist at build time. Only the
URL does.

That suggests a different shape:

At build time, construct an image URL from the post's data (title, author, tag) and sign it with an HMAC so nobody else can render on your account. One hash, microseconds, no network call.
Put that URL in the meta tag. It points at nothing that exists yet.
The first time a crawler fetches it, a rendering service draws the image with real Chrome, caches it permanently, and serves it. Every later fetch is a cache hit.

Build cost per page: one HMAC. Pages nobody shares never render at all. And if
the rendering service is down during your deploy, nothing happens, because
your build never talks to it.

Wiring it up

Disclosure before the code: I built the service this plugin talks to
(Shotpipe), so read this section as the author showing
their own tool, not a neutral survey. The pattern above stands regardless of
whose renderer you use.

npm i eleventy-plugin-shotpipe

// eleventy.config.js
module.exports = (eleventyConfig) => {
  eleventyConfig.addPlugin(require('eleventy-plugin-shotpipe'), {
    key: process.env.SHOTPIPE_KEY,
    secret: process.env.SHOTPIPE_SECRET,
    template: 'terminal',
    accent: '#5ca9ff',
  })
}

{# base layout #}
<meta property="og:image" content="{% ogImageUrl title, 'Your Name', 'blog' %}">

What ships in the built HTML is just a long URL:

<meta property="og:image"
      content="https://shotpipe.io/og?template=terminal&title=Hello&key=k_you&sig=8f2c...">

The templates are hosted server-side and parameterized by query string, so
there's no template HTML to build, host, or version yourself. You pass a title
and pick an accent color. A logo can be uploaded once and referenced by
content hash.

I timed the difference on this blog: adding the plugin changed the build time
by nothing measurable. That's not an optimization claim, it's just what "one
HMAC per page" means in practice.

What actually happens on first share

Paste your post into Slack. Slack's crawler requests the signed URL. The
service verifies the signature, renders the template in headless Chrome,
stores the PNG, and responds. That first fetch takes a couple of seconds; the
crawler waits, it's what crawlers do. Every fetch after that, from any
platform, is served from a CDN cache in milliseconds, forever. The render
happens exactly once per unique title.

Tradeoffs, honestly

It's a hosted service. Your images render on someone else's infrastructure and you need an API key (there's a free tier, no card). If you want zero external dependencies, this is not your pattern; use Satori and accept the CSS subset.
You use their templates. Four of them, parameterized. If your brand needs a fully bespoke design, a build-time approach with your own HTML gives you more control.
The URL is public. The signature means nobody can render arbitrary images on your key, but anyone can re-fetch an image you've already signed. For OG images that's fine; they're public by definition.

If you'd rather stay self-contained

Fair choice. eleventy-plugin-og-image renders with Satori at build time and
is well maintained. @vercel/og does the same rendering trick at the edge if
you're on Vercel. The build-time tax is real but modest on small sites; it
mostly bites on large sites and slow CI.

But if you've ever watched a deploy fail because Chromium didn't download, or
waited on 400 images that nobody asked for yet, it's worth questioning the
assumption underneath: the image doesn't have to exist until someone looks.

Running headless Chrome in production is a part-time job

Stevie g — Wed, 22 Jul 2026 18:32:24 +0000

It works on your laptop. You wrote fifteen lines of Puppeteer, pointed it at a
URL, got a PNG back. You wrapped it in a route, deployed it, and for about a day
it was the easiest feature you ever shipped. Then the container got OOM-killed
at 2am, the queue backed up behind it, and you spent the next week learning that
"just screenshot the page" is a systems problem wearing a fifteen-line disguise.

Here is the list of what breaks, in roughly the order it breaks, and the process
shape that stops it. It's the same list whether you're on Puppeteer or
Playwright, and whether you're rendering screenshots, PDFs, or OG images — it's
Chrome's lifecycle that's hard, not the API in front of it.

1. Memory: the first wall, and the loudest

A single headless Chrome rendering one page sits in the low hundreds of
megabytes of RSS — call it 150–300 MB depending on the page. That's per render,
and it's the good case. Chrome also leaks: keep one instance alive long enough
and RSS climbs and doesn't come back, because a browser was built to be closed
by a human at the end of the day, not kept resident for a month. On a box with a
fixed memory limit the ending is always the same — the kernel's OOM killer picks
the fattest process and kills it mid-render, and your logs show a bare SIGKILL
with no stack trace.

If you've searched puppeteer out of memory and found forty issues with no
accepted answer, this is why: there isn't a line to fix, there's a lifecycle to
manage. Two things follow. Cap how many renders share one instance and
recycle it — close the whole browser and launch a fresh one every N pages,
so leaked memory is reclaimed by process death, not by hope. And size
concurrency to RAM, not CPU: if one render is 250 MB, eight concurrent
renders is 2 GB before you've counted the OS, and "eight" is a small number.

2. Zombies: the processes that don't die

browser.close() is supposed to clean up, and usually does. But Chrome isn't
one process — it's a tree: a main process, a zygote, a renderer per page, plus
GPU and utility helpers. When Chrome crashes, or your Node process is killed
while a browser is open, or a navigation wedges the renderer, close() never
runs or never finishes, and you're left with <defunct> chrome processes
reparented to init. They hold memory and file descriptors. Do that a few
thousand times and you exhaust PIDs or FDs, and the box stops accepting work for
reasons that have nothing to do with your code.

The fix is unglamorous: reap the tree yourself. Track the browser's PID and, on
any abnormal exit, kill the whole process group instead of trusting the
library's close(). In a container, run a real init that reaps orphans
(--init, tini, or dumb-init) so PID 1 isn't your app pretending to be an init
system it isn't.

3. Cold starts: the 800ms tax

Launching Chrome costs roughly 800 milliseconds before it renders a single pixel
— process spawn, sandbox setup, the first blank page. Launch a fresh browser per
request and you pay that tax every request, where it dwarfs the actual render for
anything simple. So the instinct is to launch one browser and reuse it forever —
which walks you straight back into problem #1.

The resolution is the distinction most tutorials skip: reuse the instance,
isolate per context. A browser context is a clean, cookieless, cacheless
session inside an already-running Chrome — cheap to create, cheap to destroy,
isolated from every other render.

// not this — 800ms of startup tax on every request
const browser = await puppeteer.launch()
const page = await browser.newPage()

// this — warm instance, throwaway context per render
const context = await browser.createBrowserContext()  // cheap, isolated
const page = await context.newPage()
// …render…
await context.close()  // nothing leaks into the next render

Keep a small pool of warm instances, give each render its own fresh context,
throw the context away after, and recycle the whole instance every N renders
(problem #1). You pay the 800ms once per instance lifetime, not once per request,
and renders don't bleed into each other.

4. Pages that fight back

Your renderer navigates to a URL and waits. Sometimes the wait never ends: an
infinite redirect, a page that never fires load, a websocket that keeps the
network "busy" forever, a while(true) in someone's analytics. Without a hard
ceiling, one bad URL parks a browser until it's killed — and if you're reusing
instances, one hostile page can wedge a slot in your pool for good.

Put hard timeouts on both navigation and capture, and when one trips, kill the
instance and launch a new one — don't try to nurse it back. A browser that
hung once is not a browser you can reason about; it's carrying whatever state
caused the hang. The correct response to a sick Chrome is a fresh Chrome. It
feels wasteful and it's the single most reliability-improving rule in the whole
system.

5. Concurrency is a queue problem, not a loop

The naive version renders inline: request arrives, you launch or borrow a
browser, render, respond. Under load this is exactly how you die — a traffic
spike becomes N simultaneous browsers becomes an OOM kill becomes every in-flight
render failing at once. Rendering is expensive and bursty, which is the precise
profile a queue exists for.

Put a queue between the request and the render. The API accepts the job and
returns immediately; a pool of workers pulls jobs at a rate their RAM can
survive. A spike becomes queue depth — a number you can watch and autoscale
on — instead of a memory graph that falls off a cliff. Queue depth is your
capacity early-warning signal; RSS-at-the-OOM-line is the alternative, and it
warns you by paging you.

6. The font stack nobody mentions

Your laptop has fonts. A minimal Linux container does not. So the page that
looked right locally renders with tofu boxes where the CJK text was, blank
rectangles where the emoji were, and the wrong fallback for everything else — and
you find out from a customer's screenshot, not a test. Real page rendering means
you now own a font pipeline: a base font set, CJK coverage, an emoji font, and
the standing knowledge that a Chrome upgrade can shift glyph rendering and
quietly change your output out from under a cache.

7. Serverless doesn't make this go away

The reflex is "put it on Lambda and let someone else scale it." That moves the
problems, it doesn't remove them. You ship a special slimmed Chromium build to
fit the unzipped size limit; you eat a multi-second cold start on every
scale-up, because a warm pool is exactly what serverless won't give you; you cap
out at the function's memory and time limits, which is where playwright lambda timeout comes from; and you still own the fonts. It's a legitimate deployment
target, but it's a different set of sharp edges, not fewer of them.

The shape that survives

Put it together and the design that works isn't exotic — it's this list, applied
consistently:

![Architecture diagram: bursty traffic enters a queue; a pool of stateless, disposable workers each run a warm Chrome instance with one context per render, recycled every N renders and killed on hang; results land in an edge cache served in milliseconds.]

A queue between the request and the render — capacity is a worker count, not a prayer.
Stateless, disposable workers, each holding a small pool of warm Chrome instances.
A fresh context per render, discarded after.
Recycle each instance every N renders, so leaks die with the process.
Hard timeouts on navigation and capture; kill-and-respawn on any hang — never nurse a sick browser.
Concurrency sized to RAM, with queue depth as the capacity signal.
A maintained font and emoji stack, plus a cache version you can bump when Chrome moves.

That's the whole trick. It's also, to be blunt, most of what our workers do —
because there isn't a cleverer answer, only this list, monitored.

Disclosure before the turn: we run this as a service
(Shotpipe), so read the next two sections as the author
pointing at their own tool. The list above is true whether you build it or buy
it — I'm claiming the list is the work, not that you need us to do it.

The part the memory threads leave out

Every puppeteer out of memory thread is about pages you control — your own
dashboard, your own invoice, your own marketing page. The moment the URL comes
from your users — a link preview, an unfurl, a "screenshot my site" button —
you've added a second problem that has nothing to do with memory: the URL
might point back at you. Someone submits
http://169.254.169.254/latest/meta-data/ and your obliging headless browser
reads your cloud credentials and hands them back as a PNG. That's SSRF, and a
browser is a near-perfect engine for it, because it follows redirects and
resolves DNS for you — the two exact places the attack hides.

Fixing it properly means resolving DNS yourself, checking every resolved IP
against private, loopback, link-local, and cloud-metadata ranges, pinning the IP
you validated and connecting to that one, and re-checking on every redirect
hop. It's a module with its own test suite, not an if-statement — and it's the
part no memory-leak tutorial mentions, because those authors are rendering their
own pages. We wrote it up in screenshotting URLs you don't
control: if your renderer ever touches a
URL a stranger typed, read that before you ship.

When to run it yourself anyway

Honestly: if you render a handful of pages you control, on a schedule,
self-hosting is fine. Launch Chrome, render, close, move on — none of the above
bites at that volume, and you shouldn't pay anyone to avoid a problem you don't
have. The list starts mattering when renders get frequent, bursty, or pointed at
URLs you don't own. That's the crossover where "just screenshot the page" stops
being fifteen lines and becomes a service — ours, or the one you'll end up
building.

Dynamic OG images for Hugo, no Node - no headless Chrome

Stevie g — Tue, 21 Jul 2026 17:48:11 +0000

You picked Hugo partly because it's one Go binary. No node_modules, no
lockfile, no toolchain drift. Then you want a social card per post, and every
tutorial you find opens with npm install.

There are three real options for a Go-based site. Two of them are free and
neither needs Node — I'll go through them honestly before getting to the one I
built.

Option 1: Hugo draws the image itself (images.Text)

Hugo's image pipeline includes an images.Text filter that draws text onto an
image. No external anything: a background image, a TTF, and a template.

{{ $base := resources.Get "images/og-base.png" }}
{{ $font := resources.Get "fonts/Inter-Bold.ttf" }}
{{ $card := $base.Filter (images.Text .Title (dict
    "color" "#ffffff"
    "size" 64
    "linespacing" 12
    "x" 80 "y" 220
    "font" $font
)) }}
<meta property="og:image" content="{{ $card.Permalink }}">

That works, and if your card is "logo, brand background, title in one weight,"
it is genuinely the right answer — zero dependencies, zero third parties, zero
dollars. Know what you're signing up for though:

No automatic line wrapping. images.Text draws what you give it at the offset you give it. Long titles run off the canvas unless you split them into lines yourself in the template, which turns into a small pile of split and character-counting logic that you will tune by eye.
Layout is x/y offsets, not CSS. No flexbox, no auto-fitting type, no measuring the text you just drew. Every design change is arithmetic.
It renders during the build. Hugo caches generated images in resources/_gen, so local rebuilds are cheap — but CI with a cold cache regenerates every card, and the images ship in public/. On a 500-post site you are building and deploying 500 PNGs, including the ones nobody will ever share.

Option 2: a Node step in CI

Run hugo, then run a Node script over the output that renders cards with
Satori or Puppeteer. This is what most "Hugo OG image" search results end up
recommending, usually as a GitHub Action.

It gives you real layout (or Satori's approximation of it), and it costs you
exactly the thing you chose Hugo to avoid: a Node toolchain, a lockfile, and
either a font pipeline or a Chromium download in every CI run. Deploys now have
a way to fail that has nothing to do with your content.

Option 3: let Hugo sign a URL and render nothing

Here's the observation the other two miss. An og:image has exactly one
consumer: social crawlers. Nothing fetches that URL until somebody shares the
page. So the image doesn't need to exist when the build finishes — only the
URL does.

Which is lucky, because Hugo can compute an HMAC natively. crypto.HMAC
(aliased hmac) is a built-in template function:

{{ hmac "sha256" $secret $message }}

That's the whole dependency story. A signed image URL is a string Hugo can
build during the build, with a template, in microseconds per page. No package,
no Node, no Chromium, no image files in public/. The card renders the first
time a crawler asks for it — once, ever — and is cached from then on.

Disclosure: the service the URL points at is Shotpipe,
which I build. The pattern works with any renderer that signs requests the
same way; what makes it a particularly good fit for Hugo is that it needs no
package at all, which is not true of the Eleventy or Astro versions of this.

The partial

Save this as layouts/partials/shotpipe-og.html:

{{/* params appended in alphabetical order — that IS the canonical sort */}}
{{ $key := getenv "SHOTPIPE_KEY" }}{{ $secret := getenv "SHOTPIPE_SECRET" }}
{{ if and $key $secret }}
{{ $pairs := slice }}
{{ with .author }}{{ $pairs = $pairs | append (printf "author=%s" (replace (urlquery .) "+" "%20")) }}{{ end }}
{{ $pairs = $pairs | append (printf "key=%s" (replace (urlquery $key) "+" "%20")) }}
{{ with .tag }}{{ $pairs = $pairs | append (printf "tag=%s" (replace (urlquery .) "+" "%20")) }}{{ end }}
{{ with .template }}{{ $pairs = $pairs | append (printf "template=%s" (replace (urlquery .) "+" "%20")) }}{{ end }}
{{ $pairs = $pairs | append (printf "title=%s" (replace (urlquery .title) "+" "%20")) }}
{{ $canonical := delimit $pairs "&" }}
{{ $sig := hmac "sha256" $secret $canonical }}
<meta property="og:image" content="{{ printf "https://shotpipe.io/og?%s&sig=%s" $canonical $sig | safeURL }}">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="{{ printf "https://shotpipe.io/og?%s&sig=%s" $canonical $sig | safeURL }}">
{{ end }}

Call it from your head partial:

{{ partial "shotpipe-og.html" (dict "title" .Title "author" .Site.Params.author "tag" .Section) }}

Why the `+` → `%20` dance

This is the part worth understanding, because it's where a hand-rolled version
of this silently breaks and every URL comes back 401 invalid signature.

The string being signed is canonical: parameters sorted alphabetically by name,
each name and value percent-encoded per RFC 3986, joined with &. Both sides
have to build that string byte-for-byte identically or the HMACs differ.

Hugo's urlquery is Go's url.QueryEscape, which is almost RFC 3986 —
except it encodes a space as + rather than %20. Hence the replace. And
the parameters are appended to $pairs in alphabetical order, which means the
template never needs to sort anything; the source order is the canonical
order. Keep it that way when you add parameters.

We pin this with a test on our side: it builds the canonical string the way
this partial does — including Go's escaping rules, unicode titles, emoji, and
awkward punctuation — and asserts it is byte-identical to what the server
computes. If the recipe on this page ever drifts from the server, our test
suite fails before you find out from a broken card.

Two setup notes

Hugo's security allowlist blocks getenv for anything not prefixed HUGO_, so
add this to hugo.toml:

[security.funcs]
  getenv = ['^HUGO_', '^CI$', '^SHOTPIPE_']

Then export SHOTPIPE_KEY and SHOTPIPE_SECRET wherever Hugo builds — your
shell locally, and the environment-variable settings in Netlify, Cloudflare
Pages, or your GitHub Action. Note the partial's if and $key $secret guard:
with no key configured it emits nothing at all rather than a broken tag, so a
contributor without secrets can still build the site.

Check that it worked

$ hugo
$ grep -o 'og:image[^>]*' public/posts/my-post/index.html

# fetch the card the way a crawler would
$ curl -sI "<paste the URL>" | head -3
HTTP/2 200
content-type: image/png
x-cache: MISS

# run it again — this is what every later crawler gets
$ curl -sI "<same URL>" | grep x-cache
x-cache: HIT

A 401 means the canonical string doesn't match: check the parameter order and
that every value went through the replace. If the tag is missing entirely,
your environment variables aren't reaching Hugo — check the security.funcs
block first.

What each option actually costs

	images.Text	Node in CI	Signed URL
dependencies	none	Node + Satori or Chromium	none
build cost/page	image encode (cached)	0.1–3 s render	one HMAC
cold CI	regenerates every card	installs a toolchain	nothing to do
layout	x/y offsets, manual wrapping	real (or Satori-subset) CSS	hosted templates, parameterized
renders when	every build	every build	first share, once
third party	no	no	yes — an API key
cost	free	free (plus CI minutes)	free tier, then $14/mo

Tradeoffs, honestly

It's a hosted service. Your cards render on someone else's machines and you need an API key. If "no third parties" is a hard requirement, take images.Text and spend the afternoon on line wrapping — that's a legitimate choice, not a consolation prize.
You use hosted templates. Four of them, parameterized by title, author, tag, accent colour, and an optional logo. Fully bespoke art direction wants a build-time approach with your own HTML.
The URL is public. The signature stops anyone rendering new images on your key; it doesn't stop someone re-fetching a card you already signed. For an og:image, that's fine — they're public by definition.
Your build is decoupled from us. Worth stating plainly: because Hugo never calls the API during a build, an outage on our side cannot fail your deploy. It would delay a card rendering, nothing more.

The Go-shaped answer

Hugo users get told to bolt a JavaScript pipeline onto a Go site every time
this comes up. You don't have to. Either draw the card with the image filter
Hugo already ships, or let Hugo do the one thing it's very good at — producing
a string, fast, at build time — and let the image show up when someone actually
looks at it.

Full parameter list and the other integrations are in the
docs. The free tier is 100 renders a
month, no card; on a static blog, the renders are one per post, once, forever.

DEV Community: Stevie g

Open Graph images for Eleventy without paying the build-time tax

The two standard approaches, and what they cost

The pattern: sign now, render on first share

Wiring it up

What actually happens on first share

Tradeoffs, honestly

If you'd rather stay self-contained

Running headless Chrome in production is a part-time job

1. Memory: the first wall, and the loudest

2. Zombies: the processes that don't die

3. Cold starts: the 800ms tax

4. Pages that fight back

5. Concurrency is a queue problem, not a loop

6. The font stack nobody mentions

7. Serverless doesn't make this go away

The shape that survives

The part the memory threads leave out

When to run it yourself anyway

Dynamic OG images for Hugo, no Node - no headless Chrome

Option 1: Hugo draws the image itself (images.Text)

Option 2: a Node step in CI

Option 3: let Hugo sign a URL and render nothing

The partial

Why the + → %20 dance

Two setup notes

Check that it worked

What each option actually costs

Tradeoffs, honestly

The Go-shaped answer

Why the `+` → `%20` dance