@effing/satori 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+O'Saasy License
+
+Copyright © 2026, Trackuity BV.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @effing/satori
+
+**Render JSX to PNG using Satori, with emoji support.**
+
+> Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
+
+A thin wrapper around [Satori](https://github.com/vercel/satori) that renders JSX to PNG buffers. Includes built-in emoji support with multiple emoji styles.
+
+## Installation
+
+```bash
+npm install @effing/satori
+```
+
+## Quick Start
+
+```typescript
+import { pngFromSatori, type FontData } from "@effing/satori";
+
+// Load fonts
+const interFont: FontData = {
+  name: "Inter",
+  data: await fs.readFile("./fonts/Inter-Regular.ttf"),
+  weight: 400,
+  style: "normal"
+};
+
+// Render JSX to PNG
+const png = await pngFromSatori(
+  <div style={{
+    width: 1080,
+    height: 1920,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: "#1a1a2e",
+    color: "white",
+    fontSize: 64,
+  }}>
+    Hello World! 🚀
+  </div>,
+  {
+    width: 1080,
+    height: 1920,
+    fonts: [interFont],
+    emoji: "twemoji"
+  }
+);
+
+// png is a Buffer containing the PNG image
+await fs.writeFile("output.png", png);
+```
+
+## Concepts
+
+### Rendering Pipeline
+
+```
+JSX → Satori → SVG → Resvg → PNG Buffer
+```
+
+1. **Satori** converts JSX with CSS-like styles to SVG
+2. **Resvg** renders the SVG to a PNG buffer
+
+### Font Loading
+
+Satori requires font data to render text. You must provide fonts as ArrayBuffers:
+
+```typescript
+const fonts: FontData[] = [
+  {
+    name: "Inter",
+    data: fontBuffer,
+    weight: 400,
+    style: "normal",
+  },
+];
+```
+
+### Emoji Support
+
+The package automatically loads emoji SVGs from CDNs. Supported styles:
+
+| Style        | Source                         |
+| ------------ | ------------------------------ |
+| `twemoji`    | Twitter Emoji (default)        |
+| `openmoji`   | OpenMoji                       |
+| `blobmoji`   | Google Blob Emoji              |
+| `noto`       | Google Noto Emoji              |
+| `fluent`     | Microsoft Fluent Emoji (color) |
+| `fluentFlat` | Microsoft Fluent Emoji (flat)  |
+
+## API Overview
+
+### `pngFromSatori(template, options)`
+
+Render a JSX template to a PNG buffer.
+
+```typescript
+function pngFromSatori(
+  template: React.ReactNode,
+  options: PngFromSatoriOptions,
+): Promise<Buffer>;
+```
+
+**Options:**
+
+| Option   | Type         | Required | Description                        |
+| -------- | ------------ | -------- | ---------------------------------- |
+| `width`  | `number`     | Yes      | Output width in pixels             |
+| `height` | `number`     | Yes      | Output height in pixels            |
+| `fonts`  | `FontData[]` | Yes      | Font data for text rendering       |
+| `emoji`  | `EmojiStyle` | No       | Emoji style (default: `"twemoji"`) |
+
+### Types
+
+```typescript
+type FontData = {
+  name: string;
+  data: Buffer | ArrayBuffer;
+  weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style: "normal" | "italic";
+};
+
+type EmojiStyle =
+  | "twemoji"
+  | "openmoji"
+  | "blobmoji"
+  | "noto"
+  | "fluent"
+  | "fluentFlat";
+```
+
+## Examples
+
+### Frame Generation for Animations
+
+```typescript
+import { pngFromSatori } from "@effing/satori";
+import { tween, easeOutQuad } from "@effing/tween";
+import { annieStream } from "@effing/annie";
+
+async function* generateFrames() {
+  yield* tween(90, async ({ lower: progress }) => {
+    const scale = 1 + 0.3 * easeOutQuad(progress);
+
+    return pngFromSatori(
+      <div style={{
+        width: 1080,
+        height: 1920,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        transform: `scale(${scale})`,
+        fontSize: 72,
+        color: "white",
+      }}>
+        ✨ Animated! ✨
+      </div>,
+      { width: 1080, height: 1920, fonts }
+    );
+  });
+}
+
+const stream = annieStream(generateFrames());
+```
+
+### Multiple Font Weights
+
+```typescript
+const fonts: FontData[] = [
+  {
+    name: "Inter",
+    data: await fs.readFile("./Inter-Regular.ttf"),
+    weight: 400,
+    style: "normal"
+  },
+  {
+    name: "Inter",
+    data: await fs.readFile("./Inter-Bold.ttf"),
+    weight: 700,
+    style: "normal"
+  }
+];
+
+const png = await pngFromSatori(
+  <div style={{ display: "flex", flexDirection: "column" }}>
+    <span style={{ fontWeight: 400 }}>Regular text</span>
+    <span style={{ fontWeight: 700 }}>Bold text</span>
+  </div>,
+  { width: 800, height: 600, fonts }
+);
+```
+
+## Related Packages
+
+- [`@effing/tween`](../tween) — Step iteration for frame generation
+- [`@effing/annie`](../annie) — Package rendered frames into animations

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import satori from 'satori';
+
+/**
+ * Font data for satori rendering
+ */
+type FontData = {
+    name: string;
+    data: Buffer | ArrayBuffer;
+    weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+    style: "normal" | "italic";
+};
+/**
+ * Emoji style options for rendering
+ */
+type EmojiStyle = "twemoji" | "openmoji" | "blobmoji" | "noto" | "fluent" | "fluentFlat";
+/**
+ * Options for pngFromSatori
+ */
+type PngFromSatoriOptions = {
+    /** Frame width in pixels */
+    width: number;
+    /** Frame height in pixels */
+    height: number;
+    /** Font data for text rendering */
+    fonts: FontData[];
+    /** Emoji style to use (default: "twemoji") */
+    emoji?: EmojiStyle;
+};
+/**
+ * Render a React/JSX template to a PNG buffer using Satori
+ *
+ * @param template React element to render
+ * @param options Rendering options
+ * @returns PNG image as a Buffer
+ *
+ * @example
+ * ```tsx
+ * const png = await pngFromSatori(
+ *   <div style={{ fontSize: 48, color: "white" }}>Hello World</div>,
+ *   { width: 1080, height: 1080, fonts: [myFont] }
+ * );
+ * ```
+ */
+declare function pngFromSatori(template: Parameters<typeof satori>[0], { width, height, fonts, emoji }: PngFromSatoriOptions): Promise<Buffer>;
+
+export { type EmojiStyle, type FontData, type PngFromSatoriOptions, pngFromSatori };

package/dist/index.js

@@ -0,0 +1,63 @@
+// src/index.ts
+import { Resvg } from "@resvg/resvg-js";
+import satori from "satori";
+var emojiApis = {
+  twemoji: (code) => `https://cdnjs.cloudflare.com/ajax/libs/twemoji/16.0.1/svg/${code.toLowerCase()}.svg`,
+  openmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/openmoji@2.0.0/svg/",
+  blobmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/blob@2.0.0/svg/",
+  noto: "https://cdn.jsdelivr.net/gh/svgmoji/svgmoji/packages/svgmoji__noto/svg/",
+  fluent: (code) => `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_color.svg`,
+  fluentFlat: (code) => `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_flat.svg`
+};
+var U200D = String.fromCharCode(8205);
+var UFE0Fg = /\uFE0F/g;
+function getEmojiCode(char) {
+  return toCodePoint(char.indexOf(U200D) < 0 ? char.replace(UFE0Fg, "") : char);
+}
+function toCodePoint(unicodeSurrogates) {
+  const r = [];
+  let c = 0, p = 0, i = 0;
+  while (i < unicodeSurrogates.length) {
+    c = unicodeSurrogates.charCodeAt(i++);
+    if (p) {
+      r.push((65536 + (p - 55296 << 10) + (c - 56320)).toString(16));
+      p = 0;
+    } else if (55296 <= c && c <= 56319) {
+      p = c;
+    } else {
+      r.push(c.toString(16));
+    }
+  }
+  return r.join("-");
+}
+var emojiCache = {};
+async function loadEmoji(type, code) {
+  const key = type + ":" + code;
+  if (key in emojiCache) return emojiCache[key];
+  const api = emojiApis[type];
+  if (typeof api === "function") {
+    return emojiCache[key] = fetch(api(code)).then((r) => r.text());
+  }
+  return emojiCache[key] = fetch(`${api}${code.toUpperCase()}.svg`).then(
+    (r) => r.text()
+  );
+}
+async function pngFromSatori(template, { width, height, fonts, emoji = "twemoji" }) {
+  const overlaySvg = await satori(template, {
+    width,
+    height,
+    fonts,
+    loadAdditionalAsset: async (code, segment) => {
+      if (code === "emoji") {
+        return "data:image/svg+xml;base64," + btoa(await loadEmoji(emoji, getEmojiCode(segment)));
+      }
+      return segment;
+    }
+  });
+  const resvg = new Resvg(overlaySvg, { font: { loadSystemFonts: false } });
+  return resvg.render().asPng();
+}
+export {
+  pngFromSatori
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { Resvg } from \"@resvg/resvg-js\";\nimport satori from \"satori\";\n\n/**\n * Font data for satori rendering\n */\nexport type FontData = {\n  name: string;\n  data: Buffer | ArrayBuffer;\n  weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;\n  style: \"normal\" | \"italic\";\n};\n\n/**\n * Emoji style options for rendering\n */\nexport type EmojiStyle =\n  | \"twemoji\"\n  | \"openmoji\"\n  | \"blobmoji\"\n  | \"noto\"\n  | \"fluent\"\n  | \"fluentFlat\";\n\nconst emojiApis: Record<EmojiStyle, string | ((code: string) => string)> = {\n  twemoji: (code: string) =>\n    `https://cdnjs.cloudflare.com/ajax/libs/twemoji/16.0.1/svg/${code.toLowerCase()}.svg`,\n  openmoji: \"https://cdn.jsdelivr.net/npm/@svgmoji/openmoji@2.0.0/svg/\",\n  blobmoji: \"https://cdn.jsdelivr.net/npm/@svgmoji/blob@2.0.0/svg/\",\n  noto: \"https://cdn.jsdelivr.net/gh/svgmoji/svgmoji/packages/svgmoji__noto/svg/\",\n  fluent: (code: string) =>\n    `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_color.svg`,\n  fluentFlat: (code: string) =>\n    `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_flat.svg`,\n};\n\nconst U200D = String.fromCharCode(8205);\nconst UFE0Fg = /\\uFE0F/g;\n\nfunction getEmojiCode(char: string): string {\n  return toCodePoint(char.indexOf(U200D) < 0 ? char.replace(UFE0Fg, \"\") : char);\n}\n\nfunction toCodePoint(unicodeSurrogates: string): string {\n  const r: string[] = [];\n  let c = 0,\n    p = 0,\n    i = 0;\n\n  while (i < unicodeSurrogates.length) {\n    c = unicodeSurrogates.charCodeAt(i++);\n    if (p) {\n      r.push((65536 + ((p - 55296) << 10) + (c - 56320)).toString(16));\n      p = 0;\n    } else if (55296 <= c && c <= 56319) {\n      p = c;\n    } else {\n      r.push(c.toString(16));\n    }\n  }\n  return r.join(\"-\");\n}\n\nconst emojiCache: Record<string, Promise<string>> = {};\n\nasync function loadEmoji(type: EmojiStyle, code: string): Promise<string> {\n  const key = type + \":\" + code;\n  if (key in emojiCache) return emojiCache[key];\n\n  const api = emojiApis[type];\n  if (typeof api === \"function\") {\n    return (emojiCache[key] = fetch(api(code)).then((r) => r.text()));\n  }\n  return (emojiCache[key] = fetch(`${api}${code.toUpperCase()}.svg`).then((r) =>\n    r.text(),\n  ));\n}\n\n/**\n * Options for pngFromSatori\n */\nexport type PngFromSatoriOptions = {\n  /** Frame width in pixels */\n  width: number;\n  /** Frame height in pixels */\n  height: number;\n  /** Font data for text rendering */\n  fonts: FontData[];\n  /** Emoji style to use (default: \"twemoji\") */\n  emoji?: EmojiStyle;\n};\n\n/**\n * Render a React/JSX template to a PNG buffer using Satori\n *\n * @param template React element to render\n * @param options Rendering options\n * @returns PNG image as a Buffer\n *\n * @example\n * ```tsx\n * const png = await pngFromSatori(\n *   <div style={{ fontSize: 48, color: \"white\" }}>Hello World</div>,\n *   { width: 1080, height: 1080, fonts: [myFont] }\n * );\n * ```\n */\nexport async function pngFromSatori(\n  template: Parameters<typeof satori>[0],\n  { width, height, fonts, emoji = \"twemoji\" }: PngFromSatoriOptions,\n): Promise<Buffer> {\n  const overlaySvg = await satori(template, {\n    width,\n    height,\n    fonts,\n    loadAdditionalAsset: async (code: string, segment: string) => {\n      if (code === \"emoji\") {\n        return (\n          \"data:image/svg+xml;base64,\" +\n          btoa(await loadEmoji(emoji, getEmojiCode(segment)))\n        );\n      }\n      return segment;\n    },\n  });\n  const resvg = new Resvg(overlaySvg, { font: { loadSystemFonts: false } });\n  return resvg.render().asPng();\n}\n"],"mappings":";AAAA,SAAS,aAAa;AACtB,OAAO,YAAY;AAuBnB,IAAM,YAAqE;AAAA,EACzE,SAAS,CAAC,SACR,6DAA6D,KAAK,YAAY,CAAC;AAAA,EACjF,UAAU;AAAA,EACV,UAAU;AAAA,EACV,MAAM;AAAA,EACN,QAAQ,CAAC,SACP,qEAAqE,KAAK,YAAY,CAAC;AAAA,EACzF,YAAY,CAAC,SACX,qEAAqE,KAAK,YAAY,CAAC;AAC3F;AAEA,IAAM,QAAQ,OAAO,aAAa,IAAI;AACtC,IAAM,SAAS;AAEf,SAAS,aAAa,MAAsB;AAC1C,SAAO,YAAY,KAAK,QAAQ,KAAK,IAAI,IAAI,KAAK,QAAQ,QAAQ,EAAE,IAAI,IAAI;AAC9E;AAEA,SAAS,YAAY,mBAAmC;AACtD,QAAM,IAAc,CAAC;AACrB,MAAI,IAAI,GACN,IAAI,GACJ,IAAI;AAEN,SAAO,IAAI,kBAAkB,QAAQ;AACnC,QAAI,kBAAkB,WAAW,GAAG;AACpC,QAAI,GAAG;AACL,QAAE,MAAM,SAAU,IAAI,SAAU,OAAO,IAAI,QAAQ,SAAS,EAAE,CAAC;AAC/D,UAAI;AAAA,IACN,WAAW,SAAS,KAAK,KAAK,OAAO;AACnC,UAAI;AAAA,IACN,OAAO;AACL,QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAAA,IACvB;AAAA,EACF;AACA,SAAO,EAAE,KAAK,GAAG;AACnB;AAEA,IAAM,aAA8C,CAAC;AAErD,eAAe,UAAU,MAAkB,MAA+B;AACxE,QAAM,MAAM,OAAO,MAAM;AACzB,MAAI,OAAO,WAAY,QAAO,WAAW,GAAG;AAE5C,QAAM,MAAM,UAAU,IAAI;AAC1B,MAAI,OAAO,QAAQ,YAAY;AAC7B,WAAQ,WAAW,GAAG,IAAI,MAAM,IAAI,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC;AAAA,EACjE;AACA,SAAQ,WAAW,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,KAAK,YAAY,CAAC,MAAM,EAAE;AAAA,IAAK,CAAC,MACvE,EAAE,KAAK;AAAA,EACT;AACF;AA+BA,eAAsB,cACpB,UACA,EAAE,OAAO,QAAQ,OAAO,QAAQ,UAAU,GACzB;AACjB,QAAM,aAAa,MAAM,OAAO,UAAU;AAAA,IACxC;AAAA,IACA;AAAA,IACA;AAAA,IACA,qBAAqB,OAAO,MAAc,YAAoB;AAC5D,UAAI,SAAS,SAAS;AACpB,eACE,+BACA,KAAK,MAAM,UAAU,OAAO,aAAa,OAAO,CAAC,CAAC;AAAA,MAEtD;AACA,aAAO;AAAA,IACT;AAAA,EACF,CAAC;AACD,QAAM,QAAQ,IAAI,MAAM,YAAY,EAAE,MAAM,EAAE,iBAAiB,MAAM,EAAE,CAAC;AACxE,SAAO,MAAM,OAAO,EAAE,MAAM;AAC9B;","names":[]}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@effing/satori",
+  "version": "0.1.0",
+  "description": "Render JSX to PNG using Satori with emoji support",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "satori": "^0.12.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "satori",
+    "svg",
+    "png",
+    "jsx",
+    "emoji"
+  ],
+  "license": "O'Saasy",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}