satori-bg

library1.1.3jsnpmunverified

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.

web-framework

npm install satori-bg

github ↗package ↗

INSTALL

IMPORT

SIG · SATORI-BG

satori-bg

web-frameworkjavascriptv1.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import satori from 'satori-bg'

✗ const satori = require('satori-bg')

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

satori

✓ import satori from 'satori-bg'

✗ import { satori } from 'satori-bg'

satori is the default export, not a named export.

SatoriOptions

✓ import type { SatoriOptions } from 'satori-bg'

✗ import { SatoriOptions } from 'satori-bg'

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

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)

Debug

Known issues

breakingThis 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.

affects: >=0.0.0

gotchaJSX 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.

affects: >=0.0.0

deprecatedSome CSS properties from the original satori may not be fully supported in this fork.

fix

Test your CSS thoroughly. Rely on standard Flexbox properties.

affects: >=0.0.0

gotchaFonts 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.

affects: >=0.0.0

breakingNodes 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.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Could not resolve a font for <text>

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.

TypeError: satori is not a function

Attempted to use require() on the default import.

fix

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

Error: Yoga is not initialized

Missing yoga-layout-prebuilt dependency.

fix

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

TypeError: Cannot read property 'type' of undefined

First argument to satori is undefined or invalid.

fix

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

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

yoga-layout-prebuiltrequiredUsed for Flexbox layout calculations

svgtofontrequiredUsed for font subsetting and conversion

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/edenstrom/satori ↗

packagehttps://www.npmjs.com/package/satori-bg ↗