feat: add htmlWithOptions

.changeset/hot-eagles-draw.md

@@ -0,0 +1,20 @@
+---
+"satori-html": minor
+---
+
+**NEW** Add `htmlWithOptions` function. Currently only supports control of `tailwind`.
+
+```js
+import { htmlWithOptions } from "satori-html";
+
+const options = { tailwind: true };
+
+// Tagged Template Literal
+const tagged = htmlWithOptions(
+  options
+)`<div class="color-${color}">hello, world</div>`;
+// Function
+const fn = htmlWithOptions(options)(
+  '<div class="color-red">hello, world</div>'
+);
+```

packages/satori-html/README.md

@@ -8,13 +8,15 @@ Generate a [satori](https://github.com/vercel/satori)-friendly VDOM from a strin
 
 Unfortunately, it is built on top of React's JSX and [expects "React-elements-like objects"](https://github.com/vercel/satori#use-without-jsx). This library (`satori-html`) bridges that gap, generating the necessary VDOM object from a string of HTML.
 
-> **Note**
+> [!NOTE]
 > Satori supports a limited subset of HTML and CSS features, due to its special use case. Please use inline styles rather than class-based styling!
 
 ## Example
 
 ### API
 
+#### `html`
+
 `satori-html` exports an `html` helper, which transforms HTML strings into an object that is compatible with `satori`.
 
 ```js
@@ -38,3 +40,26 @@ const tagged = html`<div style="color: ${color};">hello, world</div>`;
 // Function
 const fn = html('<div style="color: black;">hello, world</div>');
 ```
+
+#### `htmlWithOptions`
+
+For more advanced customization `htmlWithOptions` is exposed.
+
+```js
+import { htmlWithOptions } from "satori-html";
+
+// Tagged Template Literal
+const tagged = htmlWithOptions(
+  options
+)`<div class="color-${color}">hello, world</div>`;
+// Function
+const fn = htmlWithOptions(options)(
+  '<div class="color-red">hello, world</div>'
+);
+```
+
+##### Available Options
+
+| Option     | Type      | Default | `html` Configuration |
+| ---------- | --------- | ------- | -------------------- |
+| `tailwind` | `boolean` | `false` | `true`               |

packages/satori-html/package.json

@@ -31,15 +31,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "ultrahtml": "^1.2.0"
+    "ultrahtml": "^1.5.2"
   },
   "devDependencies": {
-    "@resvg/resvg-js": "^2.1.0",
-    "@types/node": "^18.8.4",
-    "jest-image-snapshot": "^5.2.0",
-    "satori": "^0.0.38",
-    "typescript": "^4.8.4",
-    "vite": "^3.1.7",
-    "vitest": "^0.24.1"
+    "@resvg/resvg-js": "^2.6.0",
+    "@types/node": "^20.11.0",
+    "jest-image-snapshot": "^6.4.0",
+    "satori": "^0.10.11",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.0"
   }
 }

packages/satori-html/src/index.ts

@@ -77,62 +77,73 @@ interface VNode {
   };
 }
 
-export function html(
-  templates: string | TemplateStringsArray,
-  ...expressions: any[]
-): VNode {
-  const result = __html.call(null, templates, ...expressions);
-  let doc = parse(result.value.trim());
-  inliner(doc);
-  tw(doc);
+export interface SatoriHtmlOptions {
+  tailwind?: boolean;
+}
+
+export function htmlWithOption(options?: SatoriHtmlOptions) {
+  return function html(
+    templates: string | TemplateStringsArray,
+    ...expressions: any[]
+  ): VNode {
+    const result = __html.call(null, templates, ...expressions);
+    let doc = parse(result.value.trim());
+    inliner(doc);
+
+    if (options?.tailwind) {
+      tw(doc);
+    }
 
-  const nodeMap = new WeakMap();
-  let root: VNode = {
-    type: "div",
-    props: {
-      style: {
-        display: "flex",
-        flexDirection: "column",
-        width: "100%",
-        height: "100%",
+    const nodeMap = new WeakMap();
+    let root: VNode = {
+      type: "div",
+      props: {
+        style: {
+          display: "flex",
+          flexDirection: "column",
+          width: "100%",
+          height: "100%",
+        },
+        children: [],
       },
-      children: [],
-    },
-  };
-  walkSync(doc, (node, parent, index) => {
-    let newNode: any = {};
-    if (node.type === DOCUMENT_NODE) {
-      nodeMap.set(node, root);
-    } else if (node.type === ELEMENT_NODE) {
-      newNode.type = node.name;
-      const { style, "": _, ...props } = node.attributes as any;
-      if (typeof style === "object") {
-        props["style"] = {};
-        for (const [decl, value] of Object.entries(style)) {
-          props["style"][camelize(decl)] = value;
+    };
+    walkSync(doc, (node, parent, index) => {
+      let newNode: any = {};
+      if (node.type === DOCUMENT_NODE) {
+        nodeMap.set(node, root);
+      } else if (node.type === ELEMENT_NODE) {
+        newNode.type = node.name;
+        const { style, "": _, ...props } = node.attributes as any;
+        if (typeof style === "object") {
+          props["style"] = {};
+          for (const [decl, value] of Object.entries(style)) {
+            props["style"][camelize(decl)] = value;
+          }
         }
-      }
-      props.children = [] as unknown as string;
-      Object.assign(newNode, { props });
-      nodeMap.set(node, newNode);
-      if (parent) {
-        const newParent = nodeMap.get(parent);
-        newParent.props.children[index] = newNode;
-      }
-    } else if (node.type === TEXT_NODE) {
-      newNode = node.value.trim();
-      if (newNode.trim()) {
+        props.children = [] as unknown as string;
+        Object.assign(newNode, { props });
+        nodeMap.set(node, newNode);
         if (parent) {
           const newParent = nodeMap.get(parent);
-          if (parent.children.length === 1) {
-            newParent.props.children = newNode;
-          } else {
-            newParent.props.children[index] = newNode;
+          newParent.props.children[index] = newNode;
+        }
+      } else if (node.type === TEXT_NODE) {
+        newNode = node.value.trim();
+        if (newNode.trim()) {
+          if (parent) {
+            const newParent = nodeMap.get(parent);
+            if (parent.children.length === 1) {
+              newParent.props.children = newNode;
+            } else {
+              newParent.props.children[index] = newNode;
+            }
           }
         }
       }
-    }
-  });
+    });
 
-  return root;
+    return root;
+  };
 }
+
+export const html = htmlWithOption({ tailwind: true });

packages/satori-html/test/tw.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { html } from "../src/index";
+import { html, htmlWithOption } from "../src/index";
 
 describe("tailwind", () => {
   it("picks up margin util", async () => {
@@ -118,4 +118,14 @@ describe("tailwind", () => {
     const result = html`<div class="z-0">Hello world</div>`;
     expect("tw" in result.props.children?.[0].props).toEqual(true);
   });
+  it("can be disabled", async () => {
+    const result = htmlWithOption({
+      tailwind: false,
+    })`<div class="flex">Hello world</div>`;
+    expect("tw" in result.props.children?.[0].props).toEqual(false);
+  });
+  it("is disabled per default", async () => {
+    const result = htmlWithOption()`<div class="flex">Hello world</div>`;
+    expect("tw" in result.props.children?.[0].props).toEqual(false);
+  });
 });