# vercel/satori architecture

> Architecture diagram of the GitHub repository vercel/satori, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel/satori
- Repository: https://github.com/vercel/satori

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        Input["JSX Element Tree + Options"]:::io
    end
    click Input "https://github.com/vercel/satori/blob/main/src/index.ts"

    %% Handler Layer
    subgraph "Handler Layer" 
        direction TB
        Compute["compute.ts"]:::core
        Expand["expand.ts"]:::core
        ImageHandler["image.ts"]:::core
        Inheritable["inheritable.ts"]:::core
        Preprocess["preprocess.ts"]:::core
        Presets["presets.ts"]:::core
        Tailwind["tailwind.ts"]:::core
    end
    click Compute "https://github.com/vercel/satori/blob/main/src/handler/compute.ts"
    click Expand "https://github.com/vercel/satori/blob/main/src/handler/expand.ts"
    click ImageHandler "https://github.com/vercel/satori/blob/main/src/handler/image.ts"
    click Inheritable "https://github.com/vercel/satori/blob/main/src/handler/inheritable.ts"
    click Preprocess "https://github.com/vercel/satori/blob/main/src/handler/preprocess.ts"
    click Presets "https://github.com/vercel/satori/blob/main/src/handler/presets.ts"
    click Tailwind "https://github.com/vercel/satori/blob/main/src/handler/tailwind.ts"

    %% Parser Layer
    subgraph "Parser Layer"
        direction TB
        MaskParser["mask.ts"]:::core
        ShapeParser["shape.ts"]:::core
    end
    click MaskParser "https://github.com/vercel/satori/blob/main/src/parser/mask.ts"
    click ShapeParser "https://github.com/vercel/satori/blob/main/src/parser/shape.ts"

    %% Layout Engine
    subgraph "Layout Engine"
        direction TB
        YogaIndex["index.ts"]:::backend
        Prebuilt["yoga-prebuilt.ts"]:::backend
        WASM["yoga-prebuilt.wasm.ts"]:::backend
    end
    click YogaIndex "https://github.com/vercel/satori/blob/main/src/yoga/index.ts"
    click Prebuilt "https://github.com/vercel/satori/blob/main/src/yoga/yoga-prebuilt.ts"
    click WASM "https://github.com/vercel/satori/blob/main/src/yoga/yoga-prebuilt.wasm.ts"

    %% Builder Layer
    subgraph "Builder Layer"
        direction TB
        BackgroundImage["background-image.ts"]:::core
        BorderRadius["border-radius.ts"]:::core
        Border["border.ts"]:::core
        ClipPath["clip-path.ts"]:::core
        ContentMask["content-mask.ts"]:::core
        GradientLinear["gradient/linear.ts"]:::core
        GradientRadial["gradient/radial.ts"]:::core
        GradientUtils["gradient/utils.ts"]:::core
        MaskImage["mask-image.ts"]:::core
        Overflow["overflow.ts"]:::core
        Rect["rect.ts"]:::core
        Shadow["shadow.ts"]:::core
        SVGBuilder["svg.ts"]:::core
        TextDecoration["text-decoration.ts"]:::core
        TextBuilder["text.ts"]:::core
        Transform["transform.ts"]:::core
    end
    click BackgroundImage "https://github.com/vercel/satori/blob/main/src/builder/background-image.ts"
    click BorderRadius "https://github.com/vercel/satori/blob/main/src/builder/border-radius.ts"
    click Border "https://github.com/vercel/satori/blob/main/src/builder/border.ts"
    click ClipPath "https://github.com/vercel/satori/blob/main/src/builder/clip-path.ts"
    click ContentMask "https://github.com/vercel/satori/blob/main/src/builder/content-mask.ts"
    click GradientLinear "https://github.com/vercel/satori/blob/main/src/builder/gradient/linear.ts"
    click GradientRadial "https://github.com/vercel/satori/blob/main/src/builder/gradient/radial.ts"
    click GradientUtils "https://github.com/vercel/satori/blob/main/src/builder/gradient/utils.ts"
    click MaskImage "https://github.com/vercel/satori/blob/main/src/builder/mask-image.ts"
    click Overflow "https://github.com/vercel/satori/blob/main/src/builder/overflow.ts"
    click Rect "https://github.com/vercel/satori/blob/main/src/builder/rect.ts"
    click Shadow "https://github.com/vercel/satori/blob/main/src/builder/shadow.ts"
    click SVGBuilder "https://github.com/vercel/satori/blob/main/src/builder/svg.ts"
    click TextDecoration "https://github.com/vercel/satori/blob/main/src/builder/text-decoration.ts"
    click TextBuilder "https://github.com/vercel/satori/blob/main/src/builder/text.ts"
    click Transform "https://github.com/vercel/satori/blob/main/src/builder/transform.ts"

    %% Text Subsystem
    subgraph "Text Subsystem"
        direction TB
        Characters["characters.ts"]:::core
        TextIndex["index.ts"]:::core
        Measurer["measurer.ts"]:::core
        Processor["processor.ts"]:::core
    end
    click Characters "https://github.com/vercel/satori/blob/main/src/text/characters.ts"
    click TextIndex "https://github.com/vercel/satori/blob/main/src/text/index.ts"
    click Measurer "https://github.com/vercel/satori/blob/main/src/text/measurer.ts"
    click Processor "https://github.com/vercel/satori/blob/main/src/text/processor.ts"

    %% Asset Loaders
    subgraph "Asset Loaders"
        direction TB
        FontLoader["font.ts"]:::asset
        EmojiLoader["handler/image.ts"]:::asset
    end
    click FontLoader "https://github.com/vercel/satori/blob/main/src/font.ts"
    click EmojiLoader "https://github.com/vercel/satori/blob/main/src/handler/image.ts"

    %% Output Layer
    subgraph "Output Layer"
        direction TB
        OutputSVG["Final SVG String"]:::io
    end
    click OutputSVG "https://github.com/vercel/satori/blob/main/src/builder/svg.ts"

    %% Playground Consumer
    subgraph "Playground (Next.js Demo)" 
        direction TB
        Pages["playground/pages/"]:::consumer
        Components["playground/components/"]:::consumer
        Utils["playground/utils/"]:::consumer
        APIFont["playground/pages/api/font.ts"]:::consumer
    end
    click Pages "https://github.com/vercel/satori/tree/main/playground/pages/"
    click Components "https://github.com/vercel/satori/tree/main/playground/components/"
    click Utils "https://github.com/vercel/satori/tree/main/playground/utils/"
    click APIFont "https://github.com/vercel/satori/blob/main/playground/pages/api/font.ts"

    %% Data Flow
    Input -->|"normalize & expand"| Compute
    Compute --> Expand
    Expand --> Preprocess
    Preprocess --> Presets
    Presets --> Tailwind
    Tailwind --> MaskParser
    Tailwind --> ShapeParser
    MaskParser --> YogaIndex
    ShapeParser --> YogaIndex
    YogaIndex --> BackgroundImage
    YogaIndex --> BorderRadius
    YogaIndex --> Border
    YogaIndex --> ClipPath
    YogaIndex --> ContentMask
    YogaIndex --> GradientLinear
    YogaIndex --> GradientRadial
    YogaIndex --> GradientUtils
    YogaIndex --> MaskImage
    YogaIndex --> Overflow
    YogaIndex --> Rect
    YogaIndex --> Shadow
    YogaIndex --> TextBuilder
    YogaIndex --> Transform
    TextBuilder --> Characters
    TextBuilder --> Measurer
    TextBuilder --> Processor
    Characters --> FontLoader
    Measurer --> FontLoader
    Processor --> EmojiLoader
    FontLoader --> SVGBuilder
    EmojiLoader --> SVGBuilder
    SVGBuilder --> OutputSVG
    OutputSVG --> Pages
    OutputSVG --> APIFont

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064
    classDef asset fill:#E8F5E9,stroke:#1B5E20
    classDef backend fill:#FFF3E0,stroke:#E65100
    classDef consumer fill:#ECEFF1,stroke:#37474F
    classDef io fill:#F3E5F5,stroke:#6A1B9A
```
