Skip to content

Speed up OG image rendering ~9x - #2193

Merged
David Pine (IEvangelist) merged 2 commits into
mainfrom
ievangelist-faster-og-image-generation
Nov 17, 2026
Merged

David Pine (IEvangelist) merged 2 commits into
mainfrom
ievangelist-faster-og-image-generation

Conversation

@IEvangelist

Copy link
Copy Markdown
Member

Summary

The /og/**/*.png social cards were a large share of build time. Profiling showed satori layout took ~9 ms per card, but rasterizing its SVG with sharp/librsvg took ~300 ms. This PR reworks src/frontend/src/utils/og-image-renderer.ts so cards render about 9x faster on Linux CI and look the same.

Changes

  • Cached base layer. The layers shared by every card (background image, gradient, "Read on aspire.dev" CTA chip and its shadow) are rasterized once per process into a raw RGB buffer. Each card now rasterizes only its own overlay and composites it onto that base. Previously every card embedded the 400 KB background PNG as base64 in the SVG and decoded it again.
  • No per-card box-shadows. satori emits boxShadow as SVG feGaussianBlur filters, which accounted for ~65% of rasterization time. The shadows on the topic pill and title/description bubbles were invisible against the dark gradient, so they're removed. The CTA chip keeps its shadow because it's baked into the base layer.
  • Redundant masks stripped. For overflow: hidden elements satori emits both a rectangular clip-path and an equivalent rectangular mask. librsvg renders each mask offscreen, so the mask reference is dropped wherever the element already has a clip-path. Output is pixel-identical. If satori's output ever changes shape, the regex just stops matching.
  • RGB output. Cards are fully opaque, so they're encoded without an alpha channel.
  • PNG compressionLevel 9 → 6. Level 9 cost ~27 ms more per card for <2% smaller files.
  • Single satori fonts array. satori caches its font loader per array instance.

The sample OG route (/og/reference/samples/*.png) also benefits because its fallback cards use the same renderer.

Performance

Measured in a Linux container matching the CI build job (8-core-ubuntu-latest): glibc, Bun 1.4.4, 8 CPUs, sharp 0.35.4, satori 0.28.1. The harness reproduced Astro's parallelPrerender setup (4 worker threads × 4 concurrent renders) and rendered 600 cards.

Renderer 600 cards Per card
Before ~58 s ~97 ms
After ~6.5 s ~11 ms

Single-process on Windows: 292 → 37 ms per card one at a time, and 66 → 10 ms when rendering concurrently.

The output is visually indistinguishable: mean pixel difference vs. the old renderer is ~1–1.8/255, and PNGs are ~10% smaller. Cards with emoji, long wrapping titles, and no description were checked visually.

sharp tuning evaluated (no changes)

Per the sharp performance guide, I benchmarked UV_THREADPOOL_SIZE (8, 16), MALLOC_ARENA_MAX=2 with and without per-image threads pinned to 1, 8 prerender workers, and build concurrency 8. All results fell within run-to-run noise (6.0–7.5 s for 600 cards), and MALLOC_ARENA_MAX=2 alone was slower because it gives each image 8 threads on 8 cores. sharp's glibc default of 1 thread per image already fits a build that renders many images in parallel, so no CI settings were changed.

Incremental builds

Changing the renderer module invalidates the cached OG routes once. After that, CI's restored node_modules/.astro cache keeps skipping unchanged cards as before.

Third-party links and affiliations

None. The sharp performance guide linked above is reference material only.

Validation

  • bunx eslint src/utils/og-image-renderer.ts: passed.
  • bunx tsc --noEmit -p tsconfig.json: no errors in the renderer. The only error was astro:content not found in src/pages/og/[...slug].ts, because astro sync hadn't been run in the fresh worktree.
  • Ad-hoc benchmarks (temporary scripts, not committed) compared old and new renderers on timing and pixel diff, on Windows and in the Linux container.
  • No full astro build was run locally; CI covers it.

Rasterize the constant layers (background, gradient, CTA chip) once into a
cached raw base layer and composite each card's overlay onto it, instead of
re-embedding and re-decoding the 400 KB background PNG for every card.

Drop box-shadows from the per-card elements: satori emits them as SVG blur
filters, which accounted for ~65% of librsvg rasterization time while being
imperceptible against the dark gradient. The CTA chip keeps its shadow since
it is baked into the base layer.

Also reuse a single satori fonts array and use PNG compression level 6.

Measured per card: 296 ms -> 52 ms sequential, 68 ms -> 12 ms concurrent;
output is visually identical (mean pixel diff ~1/255) and ~6% smaller.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Strip satori's overflow mask references where the same element already has
an equivalent rectangular clip-path. librsvg renders each mask offscreen,
which more than doubled overlay rasterization time; output is pixel-identical.

Keep the base layer and output as RGB since cards are fully opaque, which
reduces PNG encode work and file size (~5% smaller).

Per card: 51 ms -> 37 ms sequential (~8x faster than the original renderer).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 14:13

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the shared Open Graph image renderer optimizations.

No open issues 🎉

What changed in this PR

This PR optimizes the shared Open Graph image renderer to reduce static-build time for documentation cards and sample fallback cards, with a reported ~9× speedup on Linux CI.

Changes:

  • Caches the shared background, gradient, CTA layer, and font array.
  • Removes per-card shadows and redundant overflow-mask references to reduce rasterization work.
  • Encodes opaque RGB PNGs at compression level 6 instead of 9.
File Description
src/​frontend/​src/​utils/​og-image-renderer.ts Separates cached base rendering from per-card overlays, optimizes PNG encoding, and resets derived caches in the test helper.

Review effort: Balanced

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2193. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2193 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

@sebastienros

Copy link
Copy Markdown
Contributor

The PR should have a sample of images before and after in the sizes that will be used by clients. Just to validate the quality is acceptable.

@IEvangelist
David Pine (IEvangelist) merged commit 24fa655 into main Nov 17, 2026
21 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the ievangelist-faster-og-image-generation branch November 17, 2026 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants