feat: Standalone build to support providing WASM binary manually (#705)

shuding · web-flow · commit f24d911cf1f4 · 2025-08-28T23:01:26.000+02:00
This will unblock issues like #693.
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,6 @@ coverage
 
 playground/public/yoga.wasm
 playground/tsconfig.tsbuildinfo
+
+# Vendor files
+yoga.wasm
diff --git a/README.md b/README.md
@@ -402,7 +402,29 @@ await satori(
 
 ### Runtime Support
 
-Satori can be used in browser, Node.js (>= 16), and Web Workers.
+Satori can be directly used in browser, Node.js (>= 16), and Web Workers. It bundles its underlying WASM dependencies as base64-encoded strings and loads them at runtime.
+
+If there is a limitation on dynamically loading WASM (e.g. Cloudflare Workers), you can use the Standalone Build which is mentioned below.
+
+#### Standalone Build of Satori
+
+Satori's standalone build doesn't include Yoga's WASM binary by default, and you need to load it manually before using Satori.
+
+First, you need to download the `yoga.wasm` binary from (Satori build)[https://unpkg.com/satori/] and provide it yourself. Let's use `fetch` to load it directly from the CDN as an example:
+
+```jsx
+import satori, { init } from 'satori/standalone'
+
+const res = await fetch('https://unpkg.com/satori/yoga.wasm')
+const yogaWasm = await res.arrayBuffer()
+
+await init(yogaWasm)
+
+// Now you can use satori as usual
+const svg = await satori(...)
+```
+
+Of course, you can also load the `yoga.wasm` file from your local disk via `fs.readFile` in Node.js or other methods.
 
 ### Font Embedding
 
diff --git a/package.json b/package.json
@@ -16,32 +16,34 @@
   "license": "MPL-2.0",
   "files": [
     "dist/**",
-    "wasm.js"
+    "yoga.wasm"
   ],
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./wasm": {
+    "./standalone": {
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
+        "types": "./dist/standalone.d.ts",
+        "default": "./dist/standalone.js"
       },
       "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
+        "types": "./dist/standalone.d.cts",
+        "default": "./dist/standalone.cjs"
       }
     }
   },
   "scripts": {
-    "prepare": "husky install",
+    "prepare": "husky install && pnpm run vendor",
     "dev": "pnpm run dev:default",
     "dev:default": "NODE_ENV=development tsup src/index.ts --watch --ignore-watch playground",
     "dev:playground": "turbo dev --filter=satori-playground...",
-    "build": "NODE_ENV=production pnpm run build:default",
-    "build:default": "tsup",
+    "vendor": "cp node_modules/yoga-layout/dist/binaries/yoga.wasm .",
+    "build": "pnpm run build:default && pnpm run build:standalone",
+    "build:default": "NODE_ENV=production tsup",
+    "build:standalone": "NODE_ENV=production SATORI_STANDALONE=1 tsup",
     "test": "NODE_ENV=test vitest run",
     "test:ui": "NODE_ENV=test vitest --ui --coverage.enabled",
     "test-type": "tsc -p tsconfig.json --noEmit && tsc -p playground/tsconfig.json --noEmit",
@@ -115,5 +117,10 @@
   "packageManager": "pnpm@8.7.0",
   "engines": {
     "node": ">=16"
+  },
+  "pnpm": {
+    "patchedDependencies": {
+      "yoga-layout@3.2.1": "patches/yoga-layout@3.2.1.patch"
+    }
   }
 }
diff --git a/patches/yoga-layout@3.2.1.patch b/patches/yoga-layout@3.2.1.patch
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/handler/compute.ts b/src/handler/compute.ts
@@ -10,12 +10,11 @@ import expand, { SerializedStyle } from './expand.js'
 import {
   asPointAutoPercentageLength,
   asPointPercentageLength,
-  getYoga,
   lengthToNumber,
   parseViewBox,
   v,
-  YogaNode,
 } from '../utils.js'
+import { getYoga, YogaNode } from '../yoga.js'
 import { resolveImageData } from './image.js'
 
 type SatoriElement = keyof typeof presets
diff --git a/src/index.ts b/src/index.ts
@@ -7,3 +7,4 @@ export type { Locale } from './language.js'
 
 export * from './satori.js'
 export { default } from './satori.js'
+export { init } from './yoga.js'
diff --git a/src/layout.ts b/src/layout.ts
@@ -9,9 +9,8 @@ import {
   buildXMLString,
   normalizeChildren,
   hasDangerouslySetInnerHTMLProp,
-  getYoga,
-  YogaNode,
 } from './utils.js'
+import { getYoga, YogaNode } from './yoga.js'
 import { SVGNodeToImage } from './handler/preprocess.js'
 import computeStyle from './handler/compute.js'
 import FontLoader from './font.js'
diff --git a/src/satori.ts b/src/satori.ts
@@ -5,11 +5,12 @@ import type { SatoriNode } from './layout.js'
 import layout from './layout.js'
 import FontLoader, { FontOptions } from './font.js'
 import svg from './builder/svg.js'
-import { getYoga, segment, TYoga } from './utils.js'
+import { getYoga, TYoga } from './yoga.js'
 import { detectLanguageCode, LangCode, Locale } from './language.js'
 import getTw from './handler/tailwind.js'
 import { preProcessNode } from './handler/preprocess.js'
 import { cache, inflightRequests } from './handler/image.js'
+import { segment } from './utils.js'
 
 // We don't need to initialize the opentype instances every time.
 const fontCache = new WeakMap()
diff --git a/src/text/index.ts b/src/text/index.ts
@@ -11,10 +11,8 @@ import {
   isUndefined,
   isString,
   lengthToNumber,
-  getYoga,
-  TYoga,
-  YogaNode,
 } from '../utils.js'
+import { getYoga, TYoga, YogaNode } from '../yoga.js'
 import buildText, { container } from '../builder/text.js'
 import { buildDropShadow } from '../builder/shadow.js'
 import buildDecoration from '../builder/text-decoration.js'
diff --git a/src/utils.ts b/src/utils.ts
@@ -1,18 +1,8 @@
 import type { ReactNode, ReactElement } from 'react'
 import LineBreaker from 'linebreak'
-import { loadYoga, type Yoga } from 'yoga-layout/load'
-import { type Node } from 'yoga-layout'
 
 import CssDimension from './vendor/parse-css-dimension/index.js'
 
-// Always preload Yoga.
-const loadingYoga = loadYoga()
-export function getYoga() {
-  return loadingYoga
-}
-
-export { Yoga as TYoga, Node as YogaNode }
-
 export function isReactElement(node: ReactNode): node is ReactElement {
   const type = typeof node
   if (
diff --git a/src/yoga.bundled.ts b/src/yoga.bundled.ts
@@ -0,0 +1,7 @@
+import { loadYoga } from 'yoga-layout/load'
+
+// Always preload Yoga.
+const loadingYoga = loadYoga()
+export function getYoga() {
+  return loadingYoga
+}
diff --git a/src/yoga.external.ts b/src/yoga.external.ts
@@ -0,0 +1,15 @@
+import { loadYoga, type Yoga } from 'yoga-layout/load'
+
+let resolveYoga: (yoga: Yoga) => void
+const yogaPromise: Promise<Yoga> = new Promise((resolve) => {
+  resolveYoga = resolve
+})
+
+export function init(yogaWasm: ArrayBuffer | Buffer) {
+  // Not properly typed.
+  ;(loadYoga as any)(yogaWasm).then(resolveYoga)
+}
+
+export function getYoga() {
+  return yogaPromise
+}
diff --git a/src/yoga.ts b/src/yoga.ts
@@ -0,0 +1,25 @@
+import { type Yoga } from 'yoga-layout/load'
+import { type Node } from 'yoga-layout'
+
+export { Yoga as TYoga, Node as YogaNode }
+
+export function init(wasm: ArrayBuffer | Buffer) {
+  if (process.env.SATORI_STANDALONE === '1') {
+    return import('./yoga.external.js').then((mod) => mod.init(wasm))
+  } else {
+    // Do nothing. It's bundled.
+  }
+}
+
+export function getYoga() {
+  if (process.env.SATORI_STANDALONE === '1') {
+    return import('./yoga.external.js').then((mod) => mod.getYoga())
+  } else {
+    return import('./yoga.bundled.js').then((mod) => mod.getYoga())
+  }
+}
+
+if (process.env.SATORI_STANDALONE !== '1') {
+  // Preload Yoga in bundled mode.
+  import('./yoga.bundled.js')
+}
diff --git a/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-bottom-left-with-contain-1-snap.png b/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-bottom-left-with-contain-1-snap.png
diff --git a/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-bottom-right-with-cover-1-snap.png b/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-bottom-right-with-cover-1-snap.png
diff --git a/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-top-left-with-cover-1-snap.png b/test/__image_snapshots__/image-test-tsx-test-image-test-tsx-object-fit-and-object-position-should-position-to-top-left-with-cover-1-snap.png
diff --git a/tsup.config.ts b/tsup.config.ts
@@ -1,14 +1,13 @@
-/**
- * This configuration ensures that the prebuilt Yoga (asm.js) is not included in
- * the WASM bundle.
- */
-
 import { defineConfig } from 'tsup'
 import { join } from 'path'
 import { replace } from 'esbuild-plugin-replace'
 
+const isStandaloneBuild = !!process.env.SATORI_STANDALONE
+
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: {
+    [isStandaloneBuild ? 'standalone' : 'index']: 'src/index.ts',
+  },
   splitting: false,
   sourcemap: true,
   target: 'node16',
@@ -17,11 +16,16 @@ export default defineConfig({
   },
   minify: process.env.NODE_ENV !== 'development',
   format: ['esm', 'cjs'],
-  noExternal: ['twrnc', 'emoji-regex-xs'],
+  noExternal: ['twrnc', 'emoji-regex-xs', 'yoga-layout'],
   esbuildOptions(options) {
     options.tsconfig = 'tsconfig.json'
     options.legalComments = 'external'
   },
+  env: isStandaloneBuild
+    ? {
+        SATORI_STANDALONE: '1',
+      }
+    : {},
   esbuildPlugins: [
     {
       name: 'optimize tailwind',

Original file line number	Diff line number	Diff line change
`@@ -7,3 +7,4 @@ export type { Locale } from './language.js'`
`7`	`7`
`8`	`8`	`export * from './satori.js'`
`9`	`9`	`export { default } from './satori.js'`
	`10`	`+export { init } from './yoga.js'`