safe-mdx 1.4.0 → 1.6.0

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "safe-mdx",
-  "version": "1.4.0",
-  "private": false,
-  "description": "Render MDX in React without eval",
-  "repository": "https://github.com/holocron-hq/safe-mdx",
+  "version": "1.6.0",
+  "description": "Render MDX in React without eval, works in Cloudflare Workers and Vercel Edge",
   "type": "module",
+  "main": "./dist/safe-mdx.js",
   "types": "./dist/safe-mdx.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holocron-hq/safe-mdx"
+  },
+  "homepage": "https://github.com/holocron-hq/safe-mdx",
+  "bugs": "https://github.com/holocron-hq/safe-mdx/issues",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "types": "./dist/safe-mdx.d.ts",
       "default": "./dist/safe-mdx.js"
@@ -24,15 +30,29 @@
       "browser": "./dist/html/domparser-browser.js",
       "default": "./dist/html/domparser.js"
     },
-    "./src/*": "./src/*.tsx",
-    "./package.json": "./package.json"
+    "./src": {
+      "types": "./src/safe-mdx.tsx",
+      "default": "./src/safe-mdx.tsx"
+    },
+    "./src/*": {
+      "types": "./src/*.tsx",
+      "default": "./src/*.tsx"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "keywords": [
-    "mdx"
+    "mdx",
+    "react",
+    "server-components",
+    "rsc",
+    "safe",
+    "no-eval",
+    "cloudflare-workers",
+    "edge",
+    "markdown"
   ],
   "author": "remorses <beats.by.morse@gmail.com>",
   "license": "MIT",
@@ -59,6 +79,7 @@
     "@changesets/cli": "^2.28.1",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "^4.1.11",
+    "@types/escodegen": "^0.0.10",
     "@types/estree-jsx": "^1.0.5",
     "@types/mdast": "^4.0.0",
     "@types/node": "^22.15.17",
@@ -68,12 +89,14 @@
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/coverage-v8": "^1.6.0",
     "dedent": "^1.5.1",
+    "escodegen": "^2.1.0",
     "importmap-vite-plugin": "^0.0.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
+    "rimraf": "^6.0.1",
     "tailwindcss": "^4.1.11",
     "typescript": "5.8.3",
     "vite": "^6.2.6",

package/src/esm-parser.test.ts

@@ -1,7 +1,7 @@
 import { expect, test, describe } from 'vitest'
-import { parseEsmImports, extractComponentInfo } from './esm-parser.js'
-import { mdxParse, extractImports, resolveModulePath } from './parse.js'
-import type { SafeMdxError } from './safe-mdx.js'
+import { parseEsmImports, extractComponentInfo } from './esm-parser.ts'
+import { mdxParse, extractImports, resolveModulePath } from './parse.ts'
+import type { SafeMdxError } from './safe-mdx.tsx'
 
 describe('parseEsmImports', () => {
     test('parses default imports from HTTPS URLs', () => {
@@ -67,14 +67,17 @@ import Component3 from './relative/path'
             {
               "line": 2,
               "message": "Invalid import URL: "http://insecure.com/component". Only HTTPS URLs are allowed for security reasons.",
+              "type": "esm-import",
             },
             {
               "line": 2,
               "message": "Invalid import URL: "file:///local/path". Only HTTPS URLs are allowed for security reasons.",
+              "type": "esm-import",
             },
             {
               "line": 2,
               "message": "Invalid import URL: "./relative/path". Only HTTPS URLs are allowed for security reasons.",
+              "type": "esm-import",
             },
           ]
         `)

package/src/esm-parser.ts

@@ -1,4 +1,4 @@
-import type { SafeMdxError } from './safe-mdx.js'
+import type { SafeMdxError } from './safe-mdx.tsx'
 
 export interface ParsedImport {
     componentName: string
@@ -45,6 +45,7 @@ export function parseEsmImports(
                 // Validate URL
                 if (!isValidHttpsUrl(importUrl)) {
                     onError({
+                        type: 'esm-import',
                         message: `Invalid import URL: "${importUrl}". Only HTTPS URLs are allowed for security reasons.`,
                         line: node.position?.start?.line,
                     })
@@ -69,6 +70,7 @@ export function parseEsmImports(
         }
     } catch (error) {
         onError({
+            type: 'esm-import',
             message: `Failed to parse ESM import: ${error instanceof Error ? error.message : 'Unknown error'}`,
             line: node.position?.start?.line,
         })
@@ -81,9 +83,9 @@ export function parseEsmImports(
  * Extracts component info from an import map entry
  */
 export function extractComponentInfo(importInfo: string): { importUrl: string; componentName: string } {
-    const [importUrl, componentName] = importInfo.includes('#') 
-        ? importInfo.split('#') 
-        : [importInfo, 'default']
+    const parts = importInfo.split('#')
+    const importUrl = parts[0] ?? importInfo
+    const componentName = importInfo.includes('#') ? (parts[1] ?? 'default') : 'default'
     
     return { importUrl, componentName }
 }

package/src/html/html-and-md.test.ts

@@ -55,7 +55,7 @@ async function htmlToMdxString({
                     parent &&
                     typeof index === 'number'
                 ) {
-                    const htmlValue = node.value as string
+                    const htmlValue = node.value
 
                     // Parse HTML to MDX AST with processor for markdown parsing
                     const mdxNodes = parseHtmlToMdxAst({
@@ -77,7 +77,7 @@ async function htmlToMdxString({
 
                     // Replace the HTML node with the MDX nodes
                     if (mdxNodes.length === 1) {
-                        parent.children[index] = mdxNodes[0]
+                        parent.children[index] = mdxNodes[0]!
                     } else if (mdxNodes.length > 1) {
                         parent.children.splice(index, 1, ...mdxNodes)
                     } else {

package/src/html/html-to-mdx-ast.test.ts

@@ -5,14 +5,14 @@ import {
     parseHtmlToMdxAst,
     htmlToMdxAst,
     remarkMdxJsxNormalize,
-} from './html-to-mdx-ast.js'
+} from './html-to-mdx-ast.ts'
 import { unified } from 'unified'
 import remarkMdx from 'remark-mdx'
 import remarkStringify from 'remark-stringify'
 import remarkParse from 'remark-parse'
 import type { RootContent } from 'mdast'
-import { mdxParse } from '../parse.js'
-import { MdastToJsx } from '../safe-mdx.js'
+import { mdxParse } from '../parse.ts'
+import { MdastToJsx } from '../safe-mdx.tsx'
 
 // Default components for testing
 const components = {

package/src/html/html-to-mdx-ast.ts

@@ -6,9 +6,9 @@ import type {
 } from 'mdast-util-mdx-jsx'
 import type { Processor } from 'unified'
 import { unified } from 'unified'
-import { convertAttributeNameToJSX } from './convert-attributes.js'
-import { parseHTML } from './domparser.js'
-import { remarkMdxJsxNormalize } from './remark-mdx-jsx-normalize.js'
+import { convertAttributeNameToJSX } from './convert-attributes.ts'
+import { parseHTML } from './domparser.ts'
+import { remarkMdxJsxNormalize } from './remark-mdx-jsx-normalize.ts'
 
 // Re-export the normalize plugin
 export { remarkMdxJsxNormalize }
@@ -77,7 +77,7 @@ function deindent(text: string): string {
     for (const line of lines) {
         if (line.trim()) {
             const match = line.match(/^(\s*)/)
-            if (match) {
+            if (match?.[1] != null) {
                 minIndent = Math.min(minIndent, match[1].length)
             }
         }

package/src/parse.ts

@@ -5,7 +5,7 @@ import { Root, RootContent } from 'mdast'
 import { remark } from 'remark'
 import remarkGfm from 'remark-gfm'
 import remarkMdx from 'remark-mdx'
-import { parseHtmlToMdxAst, remarkMdxJsxNormalize } from './html/html-to-mdx-ast.js'
+import { parseHtmlToMdxAst, remarkMdxJsxNormalize } from './html/html-to-mdx-ast.ts'
 
 export { parseHtmlToMdxAst, remarkMdxJsxNormalize }
 
@@ -95,6 +95,7 @@ export function remarkMarkAndUnravel() {
 
                 while (++offset < children.length) {
                     const child = children[offset]
+                    if (!child) continue
 
                     if (
                         child.type === 'mdxJsxTextElement' ||
@@ -122,6 +123,7 @@ export function remarkMarkAndUnravel() {
 
                     while (++offset < children.length) {
                         const child = children[offset]
+                        if (!child) continue
 
                         if (child.type === 'mdxJsxTextElement') {
                             // @ts-expect-error: mutate because it is faster; content model is fine.

package/src/safe-mdx.bench.tsx

@@ -1,6 +1,6 @@
 import { bench, describe } from 'vitest'
-import { mdxParse } from './parse.js'
-import { MdastToJsx } from './safe-mdx.js'
+import { mdxParse } from './parse.ts'
+import { MdastToJsx } from './safe-mdx.tsx'
 
 let longMdxContent = await fetch(
     'https://raw.githubusercontent.com/colinhacks/zod/0a49fa39348b7c72b19ddedc3b0f879bd395304b/packages/docs/content/packages/v3.mdx',

package/src/safe-mdx.test.tsx

@@ -1,11 +1,12 @@
 import dedent from 'dedent'
+import { generate } from 'escodegen'
 import React from 'react'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { expect, test } from 'vitest'
 import { z } from 'zod'
-import { mdxParse } from './parse.js'
-import { MdastToJsx, mdastBfs, type ComponentPropsSchema } from './safe-mdx.js'
-import { completeJsxTags } from './streaming.js'
+import { mdxParse } from './parse.ts'
+import { MdastToJsx, mdastBfs, type ComponentPropsSchema, type EvaluateOptions } from './safe-mdx.tsx'
+import { completeJsxTags } from './streaming.tsx'
 
 const components = {
     Heading({ level, children, ...props }) {
@@ -19,9 +20,9 @@ const components = {
     },
 }
 
-function render(code, componentPropsSchema?: ComponentPropsSchema, allowClientEsmImports?: boolean, addMarkdownLineNumbers?: boolean) {
+function render(code, componentPropsSchema?: ComponentPropsSchema, allowClientEsmImports?: boolean, addMarkdownLineNumbers?: boolean, scope?: Record<string, any>, evaluateOptions?: EvaluateOptions) {
     const mdast = mdxParse(code)
-    const visitor = new MdastToJsx({ markdown: code, mdast, components, componentPropsSchema, allowClientEsmImports, addMarkdownLineNumbers })
+    const visitor = new MdastToJsx({ markdown: code, mdast, components, componentPropsSchema, allowClientEsmImports, addMarkdownLineNumbers, scope, evaluateOptions })
     const result = visitor.run()
     const html = renderToStaticMarkup(result)
     // console.log(JSON.stringify(result, null, 2))
@@ -483,6 +484,7 @@ test('missing components are ignored', () => {
           {
             "line": 1,
             "message": "Unsupported jsx component MissingComponent",
+            "type": "missing-component",
           },
         ],
         "html": "",
@@ -520,22 +522,27 @@ test('props parsing', () => {
           {
             "line": 8,
             "message": "Failed to evaluate expression attribute: expression2={Boolean(1)}. Functions are not supported",
+            "type": "expression",
           },
           {
             "line": 8,
             "message": "Expressions in jsx prop not evaluated: (expression2={Boolean(1)})",
+            "type": "expression",
           },
           {
             "line": 9,
             "message": "Unsupported jsx component SomeComponent in attribute",
+            "type": "missing-component",
           },
           {
             "line": 9,
             "message": "Failed to evaluate expression attribute: jsx={<SomeComponent />}. visitor "JSXElement" is not supported",
+            "type": "expression",
           },
           {
             "line": 9,
             "message": "Expressions in jsx prop not evaluated: (jsx={<SomeComponent />})",
+            "type": "expression",
           },
         ],
         "html": "<h1 num="2" doublequote="a &quot; string" quote="a &#x27; string" backTick="some undefined value" expression1="4" someJson="[object Object]"><p>hi</p></h1>",
@@ -2292,8 +2299,8 @@ test('mdx jsx with unknown components are ignored', () => {
     
     // Check that errors were generated for unknown components
     expect(errors).toHaveLength(2)
-    expect(errors[0].message).toContain('Unsupported jsx component CustomElement')
-    expect(errors[1].message).toContain('Unsupported jsx component AnotherUnknown')
+    expect(errors[0]!.message).toContain('Unsupported jsx component CustomElement')
+    expect(errors[1]!.message).toContain('Unsupported jsx component AnotherUnknown')
     
     expect(result).toMatchInlineSnapshot(`
       <React.Fragment>
@@ -2531,16 +2538,19 @@ test('component props schema validation with zod', () => {
             "line": 5,
             "message": "Invalid props for component "Heading" at "level": Too big: expected number to be <=6",
             "schemaPath": "level",
+            "type": "validation",
           },
           {
             "line": 7,
             "message": "Invalid props for component "Cards" at "count": Too small: expected number to be >0",
             "schemaPath": "count",
+            "type": "validation",
           },
           {
             "line": 9,
             "message": "Invalid props for component "Cards" at "count": Invalid input: expected number, received string",
             "schemaPath": "count",
+            "type": "validation",
           },
         ],
         "html": "<h1 title="test">Valid heading</h1><div count="3" variant="outline">Valid cards</div><h1 title="test">Invalid heading - level too high</h1><div count="-1">Invalid cards - negative count</div><div count="not a number">Invalid cards - wrong type</div>",
@@ -2578,6 +2588,66 @@ test('component props schema validation with zod', () => {
     `)
 })
 
+test('onError callback is called for each error', () => {
+    const errors: any[] = []
+    const code = dedent`
+        <Missing>should error</Missing>
+        
+        <Heading level={10}>invalid level</Heading>
+    `
+    const componentPropsSchema: ComponentPropsSchema = {
+        Heading: z.object({
+            level: z.number().min(1).max(6),
+        }),
+    }
+    const mdast = mdxParse(code)
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast,
+        components,
+        componentPropsSchema,
+        onError: (err) => errors.push(err),
+    })
+    visitor.run()
+    expect(errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 1,
+          "message": "Unsupported jsx component Missing",
+          "type": "missing-component",
+        },
+        {
+          "line": 3,
+          "message": "Invalid props for component "Heading" at "level": Too big: expected number to be <=6",
+          "schemaPath": "level",
+          "type": "validation",
+        },
+      ]
+    `)
+    // errors array and onError callback should have the same errors
+    expect(visitor.errors).toEqual(errors)
+})
+
+test('onError callback can throw to stop rendering', () => {
+    const code = dedent`
+        <Missing>should throw</Missing>
+        
+        <Heading>should not reach</Heading>
+    `
+    const mdast = mdxParse(code)
+    expect(() => {
+        const visitor = new MdastToJsx({
+            markdown: code,
+            mdast,
+            components,
+            onError: (err) => {
+                throw new Error(`MDX error on line ${err.line}: ${err.message}`)
+            },
+        })
+        visitor.run()
+    }).toThrow('MDX error on line 1: Unsupported jsx component Missing')
+})
+
 test('mdx expressions evaluation', () => {
     expect(
         render(dedent`
@@ -2635,10 +2705,12 @@ test('mdx expressions with unsupported functions', () => {
           {
             "line": 1,
             "message": "Failed to evaluate expression: Math.max(5, 10). Functions are not supported",
+            "type": "expression",
           },
           {
             "line": 2,
             "message": "Failed to evaluate expression: console.log("test"). Functions are not supported",
+            "type": "expression",
           },
         ],
         "html": "<p>Math function: 
@@ -2750,11 +2822,13 @@ test('validation error includes schema path', () => {
             "line": 1,
             "message": "Invalid props for component "Heading" at "user.age": Too small: expected number to be >=0",
             "schemaPath": "user.age",
+            "type": "validation",
           },
           {
             "line": 1,
             "message": "Invalid props for component "Heading" at "settings.theme": Invalid option: expected one of "light"|"dark"",
             "schemaPath": "settings.theme",
+            "type": "validation",
           },
         ],
         "html": "<h1 user="[object Object]" settings="[object Object]">Complex validation</h1>",
@@ -2887,6 +2961,7 @@ test('mdxJsxExpressionAttribute edge cases', () => {
           {
             "line": 3,
             "message": "Failed to evaluate expression attribute: ...{null: null, undefined: undefined}. undefined is undefined",
+            "type": "expression",
           },
         ],
         "html": "<h1 title="empty spread">Empty spread</h1><h1 title="null/undefined values">Null/undefined</h1><h1 array="1,2,3" object="[object Object]" title="complex values">Complex types</h1>",
@@ -2980,12 +3055,12 @@ test('ESM imports error handling', () => {
     expect(visitor.errors.length).toBe(4)
     
     // First two errors are for invalid imports
-    expect(visitor.errors[0].message).toContain('Invalid import URL')
-    expect(visitor.errors[1].message).toContain('Invalid import URL')
+    expect(visitor.errors[0]!.message).toContain('Invalid import URL')
+    expect(visitor.errors[1]!.message).toContain('Invalid import URL')
     
     // Last two errors are for unsupported components
-    expect(visitor.errors[2].message).toContain('Unsupported jsx component Button')
-    expect(visitor.errors[3].message).toContain('Unsupported jsx component Component')
+    expect(visitor.errors[2]!.message).toContain('Unsupported jsx component Button')
+    expect(visitor.errors[3]!.message).toContain('Unsupported jsx component Component')
 })
 
 test('jsx components in attributes', () => {
@@ -3143,14 +3218,17 @@ test("jsx components in attributes error handling", () => {
         {
           "line": 3,
           "message": "Unsupported jsx component UnsupportedComponent in attribute",
+          "type": "missing-component",
         },
         {
           "line": 3,
           "message": "Failed to evaluate expression attribute: icon={<UnsupportedComponent />}. visitor "JSXElement" is not supported",
+          "type": "expression",
         },
         {
           "line": 3,
           "message": "Expressions in jsx prop not evaluated: (icon={<UnsupportedComponent />})",
+          "type": "expression",
         },
       ]
     `)
@@ -3609,7 +3687,169 @@ test('modules prop: unresolved import produces error', () => {
         {
           "line": 3,
           "message": "Unsupported jsx component Missing",
+          "type": "missing-component",
         },
       ]
     `)
 })
+
+test('modules prop: rendering a subset of mdast with import nodes prepended resolves components', () => {
+    // Simulates the pattern used by holocron: the full mdast is split into
+    // sections, and import nodes (mdxjsEsm) are prepended to each section's
+    // nodes so SafeMdxRenderer can resolve imported components.
+    function CustomHero({ title }: { title: string }) {
+        return <div data-testid="hero">{title}</div>
+    }
+
+    const code = dedent`
+        import { CustomHero } from './components/hero'
+
+        # Main content
+
+        <CustomHero title="Hello" />
+    `
+    const mdast = mdxParse(code)
+
+    // Split: extract import nodes and content nodes separately
+    const importNodes = mdast.children.filter((node) => node.type === 'mdxjsEsm')
+    const contentNodes = mdast.children.filter((node) => node.type !== 'mdxjsEsm')
+
+    // Render only content nodes WITH import nodes prepended
+    const syntheticRoot = { type: 'root' as const, children: [...importNodes, ...contentNodes] }
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast: syntheticRoot,
+        components,
+        modules: {
+            './components/hero.tsx': { CustomHero },
+        },
+        baseUrl: './',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    expect(html).toContain('data-testid="hero"')
+    expect(html).toContain('Hello')
+    expect(visitor.errors).toMatchInlineSnapshot(`[]`)
+})
+
+test('modules prop: rendering subset WITHOUT import nodes fails to resolve components', () => {
+    // Demonstrates the bug: if import nodes are NOT prepended, the component
+    // is not found and a missing-component error is produced.
+    function CustomHero({ title }: { title: string }) {
+        return <div data-testid="hero">{title}</div>
+    }
+
+    const code = dedent`
+        import { CustomHero } from './components/hero'
+
+        <CustomHero title="Hello" />
+    `
+    const mdast = mdxParse(code)
+
+    // Only render the JSX node WITHOUT the import node
+    const contentNodes = mdast.children.filter((node) => node.type !== 'mdxjsEsm')
+    const syntheticRoot = { type: 'root' as const, children: contentNodes }
+    const visitor = new MdastToJsx({
+        markdown: code,
+        mdast: syntheticRoot,
+        components,
+        modules: {
+            './components/hero.tsx': { CustomHero },
+        },
+        baseUrl: './',
+    })
+    const result = visitor.run()
+    const html = renderToStaticMarkup(result)
+    // Without import nodes, the component is not resolved
+    expect(html).not.toContain('data-testid="hero"')
+    expect(visitor.errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 3,
+          "message": "Unsupported jsx component CustomHero",
+          "type": "missing-component",
+        },
+      ]
+    `)
+})
+
+test('scope with function in jsx prop receiving object arg', () => {
+    const scope = {
+        formatTitle: (opts: { text: string; uppercase?: boolean }) => {
+            return opts.uppercase ? opts.text.toUpperCase() : opts.text
+        },
+    }
+
+    const code = dedent`
+        <Heading level={1} title={formatTitle({ text: "hello world", uppercase: true })}>Content</Heading>
+    `
+
+    const { html, errors } = render(code, undefined, undefined, undefined, scope)
+    expect(errors).toMatchInlineSnapshot(`[]`)
+    expect(html).toMatchInlineSnapshot(`"<h1 title="HELLO WORLD">Content</h1>"`)
+})
+
+test('scope with variables and functions in inline expressions', () => {
+    const scope = {
+        greeting: 'Hello',
+        getName: (user: { first: string; last: string }) => `${user.first} ${user.last}`,
+    }
+
+    const code = dedent`
+        {greeting} {getName({ first: "John", last: "Doe" })}
+    `
+
+    const { html, errors } = render(code, undefined, undefined, undefined, scope)
+    expect(errors).toMatchInlineSnapshot(`[]`)
+    expect(html).toMatchInlineSnapshot(`"HelloJohn Doe"`)
+})
+
+test('scope with function in spread attribute', () => {
+    const scope = {
+        getProps: (config: { level: number }) => ({ level: config.level }),
+    }
+
+    const code = dedent`
+        <Heading {...getProps({ level: 2 })}>Spread test</Heading>
+    `
+
+    const { html, errors } = render(code, undefined, undefined, undefined, scope)
+    expect(errors).toMatchInlineSnapshot(`[]`)
+    expect(html).toMatchInlineSnapshot(`"<h1>Spread test</h1>"`)
+})
+
+test('scope with .map and arrow function callback fails without generate', () => {
+    const scope = {
+        items: [{ name: 'Alice' }, { name: 'Bob' }, { name: 'Charlie' }],
+    }
+
+    const code = dedent`
+        {items.map(item => item.name).join(", ")}
+    `
+
+    const { html, errors } = render(code, undefined, undefined, undefined, scope)
+    expect(errors).toMatchInlineSnapshot(`
+      [
+        {
+          "line": 1,
+          "message": "Failed to evaluate expression: items.map(item => item.name).join(", "). Expected options.generate to be the "generate" function from "escodegen"",
+          "type": "expression",
+        },
+      ]
+    `)
+    expect(html).toMatchInlineSnapshot(`""`)
+})
+
+test('scope with .map and arrow function callback works with generate', () => {
+    const scope = {
+        items: [{ name: 'Alice' }, { name: 'Bob' }, { name: 'Charlie' }],
+    }
+
+    const code = dedent`
+        {items.map(item => item.name).join(", ")}
+    `
+
+    const { html, errors } = render(code, undefined, undefined, undefined, scope, { generate })
+    expect(errors).toMatchInlineSnapshot(`[]`)
+    expect(html).toMatchInlineSnapshot(`"Alice, Bob, Charlie"`)
+})