How vercel/satori works
Project type and purpose
• Satori is an open‑source TypeScript library (monorepo) whose core purpose is to convert a JSX/HTML+CSS element tree into a standalone SVG string.
• It supports multiple runtimes (Node.js, browser, edge functions, Web Workers) and multiple layout backends (asm.js, native, WebAssembly via Yoga).
• There is also a “playground” Next.js sample app showing live demos and an API endpoint that uses Satori.
File structure
Top‑level:
• configuration (.eslintrc.json, tsconfig.json, tsup.config.ts, vitest.config.ts, pnpm-workspace.yaml, GitHub workflows)
• package.json for the core library
• src/ – the core library code
• test/ – unit and snapshot tests (Vitest)
• playground/ – a standalone Next.js application demonstrating usage
src/ layout shows a clear modular, pipeline architecture:
• src/index.ts – public entry point
• src/handler/ – preprocessing and option‐handling (compute, expand, tailwind CSS, presets)
• src/builder/ – converting internal layout + style models into SVG primitives (rect, text, gradient, mask, clip‐path)
• src/text/ – text measurement, grapheme/image mapping, processors
• src/yoga/ – integration wrapper for the Yoga layout engine (asm.js, WASM, or native)
• src/utils.ts, src/types.d.ts, src/font.ts, src/language.ts – helper modules
README insights
• The library exposes a single async function satori(elementTree, options)
• Options drive width/height, fonts, locale, debug, embedFont, graphemeImages, loadAdditionalAsset, and wasm initialization
• Under the hood the flow is: JSX → handler → parser → Yoga layout → builder → SVG string
• The playground demonstrates usage in a Next.js API route and static pages, using React components and the edge runtime
a. Main components
1. Input Layer
• JSX Element Tree + Options (fonts, images, locale, embed/debug flags)
2. Handler Layer (src/handler)
• Option normalization, CSS preset application, tailwind expansion, preprocess hooks
3. Parser Layer (src/parser)
4. Layout Engine (src/yoga)
• Flexbox layout via Yoga (asm.js, WASM, or native) → produces node tree with positional data
5. Builder Layer (src/builder, src/text)
• Convert each layout node + style into SVG primitives
• Text measurement and conversion to <path> or <text>
• Gradient, mask, clip‑path, shadow, filter builders
6. Asset Loaders
• Font loader (ArrayBuffer/Buffer)
• Emoji/grapheme image loader (base64 or URL)
• Optionally dynamically via loadAdditionalAsset callback
7. Output Layer
• Final SVG string
b. Relationships & interactions
Input → Handler → Parser → Layout Engine
Layout Engine → Builder
Builder → Output
Asset Loaders feed both Handler and Builder (for font metrics and grapheme images)
WASM/Nativemodule initialization precedes Layout Engine
c. Architectural patterns & design principles
• Pipeline architecture (staged processing)
• Modular separation of concerns (handler, parser, layout, builder, utils)
• Adapter pattern for Yoga backends (asm.js, WASM, native)
• Plugin‐style extensibility for asset loading and custom presets
d. Key technologies & libraries
• TypeScript, TSUP (bundler), Vitest (tests)
• React‑style JSX input, no React runtime used
• YogaLayout for Flexbox computations (via asm.js/WASM/native)
• Node.js and browser/Web Worker compatibility
• Next.js (playground) demonstrating Edge Functions