Satori (fork with basic support)

1.1.3 verified Fri May 01 auth: no javascript maintenance

Satori-bg is a community fork of Vercel's Satori library (v1.1.3) that adds basic support for background images on HTML elements. The original Satori is an enlightened library to convert HTML and CSS (via JSX) to SVG, primarily used for generating Open Graph images and social cards. It uses a Flexbox layout engine (Yoga) and supports a limited subset of HTML and CSS. Satori is maintained actively by Vercel and releases are frequent. Differentiators from alternatives like Puppeteer or Playwright: no headless browser needed, works on edge runtimes, produces deterministic SVG output. This fork specifically adds background-image support (not present in original Satori). Node.js >=16 required, ships TypeScript types.

Common errors

error Error: Could not resolve a font for <text> ↓

cause No font was provided in the 'fonts' option that matches the text style.

fix

Add a font entry with the correct name, weight, and style matching your text.

error TypeError: satori is not a function ↓

cause Attempted to use require() on the default import.

fix

Use ES module import syntax: import satori from 'satori-bg'

error Error: Yoga is not initialized ↓

cause Missing yoga-layout-prebuilt dependency.

fix

Install yoga-layout-prebuilt: npm install yoga-layout-prebuilt

error TypeError: Cannot read property 'type' of undefined ↓

cause First argument to satori is undefined or invalid.

fix

Ensure you pass a valid JSX element or object with type and props.

Warnings

breaking This is a fork of satori. Do NOT expect full compatibility with the original satori API. ↓

fix Check the fork's documentation for differences. Use original satori if you don't need background-image support.

gotcha JSX is not supported in all environments. If you are not using a JSX transpiler, you must use object syntax. ↓

fix Use the object format (type, props) instead of JSX tags.

deprecated Some CSS properties from the original satori may not be fully supported in this fork. ↓

fix Test your CSS thoroughly. Rely on standard Flexbox properties.

gotcha Fonts must be provided via 'fonts' option. Using system fonts will not work. ↓

fix Fetch or read font files and pass them as ArrayBuffer or Buffer in the fonts array.

breaking Nodes using this library require at least Node.js 16 due to dependency on ES modules and modern APIs. ↓

fix Upgrade Node.js to version 16 or later.

Install

npm install satori-bg

yarn add satori-bg

pnpm add satori-bg

Imports

default

wrong

const satori = require('satori-bg')

correct

import satori from 'satori-bg'

ESM-only since v1.0. CommonJS require will fail.

satori

wrong

import { satori } from 'satori-bg'

correct

import satori from 'satori-bg'

satori is the default export, not a named export.

SatoriOptions

wrong

import { SatoriOptions } from 'satori-bg'

correct

import type { SatoriOptions } from 'satori-bg'

TypeScript type, not a runtime value. Use 'import type'.

Quickstart

Demonstrates using satori-bg with a non-JSX object, fetching a font, and including a background image.

import satori from 'satori-bg'

const robotoUrl = 'https://fonts.cdnfonts.com/s/103369/Roboto-Regular.woff'
const fontResponse = await fetch(robotoUrl)
const fontData = await fontResponse.arrayBuffer()

const svg = await satori(
  {
    type: 'div',
    props: {
      children: 'Hello, world!',
      style: {
        color: 'black',
        fontSize: 48,
        fontWeight: 700,
        backgroundColor: '#f0f0f0',
        padding: 20,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        backgroundImage: 'url(https://example.com/bg.png)'
      }
    }
  },
  {
    width: 600,
    height: 400,
    fonts: [
      {
        name: 'Roboto',
        data: fontData,
        weight: 700,
        style: 'normal'
      }
    ]
  }
)

console.log(svg)