{"id":26364,"library":"satori-bg","title":"Satori (fork with basic support)","description":"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.","status":"maintenance","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/edenstrom/satori","tags":["javascript","HTML","JSX","SVG","converter","renderer","typescript"],"install":[{"cmd":"npm install satori-bg","lang":"bash","label":"npm"},{"cmd":"yarn add satori-bg","lang":"bash","label":"yarn"},{"cmd":"pnpm add satori-bg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for Flexbox layout calculations","package":"yoga-layout-prebuilt","optional":false},{"reason":"Used for font subsetting and conversion","package":"svgtofont","optional":false}],"imports":[{"note":"ESM-only since v1.0. CommonJS require will fail.","wrong":"const satori = require('satori-bg')","symbol":"default","correct":"import satori from 'satori-bg'"},{"note":"satori is the default export, not a named export.","wrong":"import { satori } from 'satori-bg'","symbol":"satori","correct":"import satori from 'satori-bg'"},{"note":"TypeScript type, not a runtime value. Use 'import type'.","wrong":"import { SatoriOptions } from 'satori-bg'","symbol":"SatoriOptions","correct":"import type { SatoriOptions } from 'satori-bg'"}],"quickstart":{"code":"import satori from 'satori-bg'\n\nconst robotoUrl = 'https://fonts.cdnfonts.com/s/103369/Roboto-Regular.woff'\nconst fontResponse = await fetch(robotoUrl)\nconst fontData = await fontResponse.arrayBuffer()\n\nconst svg = await satori(\n  {\n    type: 'div',\n    props: {\n      children: 'Hello, world!',\n      style: {\n        color: 'black',\n        fontSize: 48,\n        fontWeight: 700,\n        backgroundColor: '#f0f0f0',\n        padding: 20,\n        display: 'flex',\n        alignItems: 'center',\n        justifyContent: 'center',\n        backgroundImage: 'url(https://example.com/bg.png)'\n      }\n    }\n  },\n  {\n    width: 600,\n    height: 400,\n    fonts: [\n      {\n        name: 'Roboto',\n        data: fontData,\n        weight: 700,\n        style: 'normal'\n      }\n    ]\n  }\n)\n\nconsole.log(svg)","lang":"typescript","description":"Demonstrates using satori-bg with a non-JSX object, fetching a font, and including a background image."},"warnings":[{"fix":"Check the fork's documentation for differences. Use original satori if you don't need background-image support.","message":"This is a fork of satori. Do NOT expect full compatibility with the original satori API.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Use the object format (type, props) instead of JSX tags.","message":"JSX is not supported in all environments. If you are not using a JSX transpiler, you must use object syntax.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Test your CSS thoroughly. Rely on standard Flexbox properties.","message":"Some CSS properties from the original satori may not be fully supported in this fork.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Fetch or read font files and pass them as ArrayBuffer or Buffer in the fonts array.","message":"Fonts must be provided via 'fonts' option. Using system fonts will not work.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade Node.js to version 16 or later.","message":"Nodes using this library require at least Node.js 16 due to dependency on ES modules and modern APIs.","severity":"breaking","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Add a font entry with the correct name, weight, and style matching your text.","cause":"No font was provided in the 'fonts' option that matches the text style.","error":"Error: Could not resolve a font for <text>"},{"fix":"Use ES module import syntax: import satori from 'satori-bg'","cause":"Attempted to use require() on the default import.","error":"TypeError: satori is not a function"},{"fix":"Install yoga-layout-prebuilt: npm install yoga-layout-prebuilt","cause":"Missing yoga-layout-prebuilt dependency.","error":"Error: Yoga is not initialized"},{"fix":"Ensure you pass a valid JSX element or object with type and props.","cause":"First argument to satori is undefined or invalid.","error":"TypeError: Cannot read property 'type' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}