Satori

Satori is a TypeScript library that renders HTML and CSS as SVG, giving JavaScript and Node.js applications a way to generate images programmatically instead of relying on a headless browser. It implements its own layout engine (via Yoga’s flexbox model), font shaping, and CSS subset directly in JavaScript, so it runs in constrained environments like serverless functions and edge runtimes.

Built and maintained by Vercel, Satori is best known as the engine behind dynamic Open Graph image generation — accepting JSX-like element trees with inline styles and producing an SVG string that can be rasterized to PNG. It supports a deliberately curated subset of CSS (flexbox, borders, gradients, text wrapping, custom fonts, emoji) rather than the full spec, trading completeness for speed and portability.

What You Get

• A satori() function that renders JSX/React-element trees plus font buffers into an SVG string, runnable in Node.js, Deno, browsers, and edge/serverless runtimes
• A self-contained flexbox layout engine (via the yoga-layout WASM/JS binding) implementing CSS flexbox semantics without a browser
• A curated CSS-in-JS style subset: borders, border-radius, gradients (linear/radial/conic), box-shadow, transforms, clip-path, and text properties like line-clamp and letter-spacing
• Built-in emoji and multi-language (CJK, RTL) text segmentation and shaping via linebreak and custom Unicode handling
• A satori/wasm and standalone build variant for environments without native Node.js APIs (e.g. Cloudflare Workers)
• An experimental built-in JSX runtime (satori/jsx) so consumers don’t need to depend on React just to author element trees

Common Use Cases

• Generating dynamic Open Graph and social-card images at request time for blog posts, product pages, or user profiles
• Producing programmatic certificates, badges, or receipts as SVG/PNG without a browser dependency
• Rendering data-driven graphics (e.g. personalized share images) inside serverless functions or edge middleware where spinning up a headless browser is impractical
• Building custom screenshot/thumbnail services that need predictable, fast SVG output instead of full-page browser rendering

Under The Hood

Architecture: src/satori.ts is the entry point — it initializes a Yoga WASM/JS layout tree, wraps the caller’s element in an inherited-style context (default font, color, whitespace), and hands off to src/layout.ts, an async generator that walks the element tree, resolves per-node styles via src/handler/compute.ts, and mutates the Yoga node graph. Once layout is calculated (root.calculateLayout), the same generator resumes to walk the tree a second time and emit SVG fragments, which src/builder/*.ts modules (rect, text, gradient, border-radius, clip-path, shadow, transform) turn into path/shape primitives, finally assembled by src/builder/svg.ts into a single <svg> string. Font shaping lives in src/font.ts via @shuding/opentype.js, and image embedding/caching is handled in src/handler/image.ts.

Tech Stack: Pure TypeScript (98.7% of the codebase) with yoga-layout for flexbox, @shuding/opentype.js for glyph outlines, css-to-react-native/css-gradient-parser/postcss-value-parser/parse-css-color for CSS parsing, and linebreak for Unicode text segmentation. Built with tsup, targeting multiple output formats (ESM/CJS/standalone WASM/browser) so the same source ships to Node.js, Deno, browsers, and edge runtimes without a bundler-specific fork.

Code Quality: The test/ directory holds 48 focused test files (layout, flexbox-advanced, gradient, emoji, language, line-clamp, transform, etc.) run under Vitest with image-snapshot comparisons, plus a dedicated browser-build.mjs smoke test and strict TypeScript (tsc --noEmit) and ESLint/Prettier checks wired into ci-check. Types are used throughout (exported SatoriOptions, FontOptions, SatoriNode), and internal modules are small and single-purpose (e.g. transform-origin.ts, language.ts are each under 100 lines).

API Design: The public surface is a single async function — satori(element, options) — that mirrors familiar JSX/React-element conventions, so anyone who knows React props can start immediately; the fonts array and width/height options are the only required inputs beyond the tree itself. Advanced hooks (loadAdditionalAsset, onNodeDetected, graphemeImages) are opt-in and don’t complicate the basic path, and the library documents its supported CSS subset explicitly rather than silently failing on unsupported properties.