Repository navigation
Speed up OG image rendering ~9x - #2193
Conversation
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>
There was a problem hiding this comment.
🟢 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
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
|
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. |
Summary
The
/og/**/*.pngsocial 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 reworkssrc/frontend/src/utils/og-image-renderer.tsso cards render about 9x faster on Linux CI and look the same.Changes
boxShadowas SVGfeGaussianBlurfilters, 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.overflow: hiddenelements satori emits both a rectangularclip-pathand an equivalent rectangularmask. 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.compressionLevel9 → 6. Level 9 cost ~27 ms more per card for <2% smaller files.fontsarray. 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'sparallelPrerendersetup (4 worker threads × 4 concurrent renders) and rendered 600 cards.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=2with 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), andMALLOC_ARENA_MAX=2alone 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/.astrocache 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 wasastro:contentnot found insrc/pages/og/[...slug].ts, becauseastro synchadn't been run in the fresh worktree.astro buildwas run locally; CI covers it.