react-email-rails 0.2.0 → 0.3.0

package/dist/document.d.ts

@@ -1,5 +1,5 @@
 import { type Extensions } from "@tiptap/core";
-import type { DroppedNode, RenderResult } from "./runtime.js";
+import type { DroppedNode, ParseResult, RenderResult } from "./runtime.js";
 export type { DroppedNode };
 export type DocumentRenderer = {
     buildExtensions: (context: unknown) => Extensions;
@@ -15,4 +15,13 @@ export type RenderDocumentRequest = {
     context?: unknown;
     preview?: string | null;
 };
+export type ParseDocumentRequest = {
+    kind: "parse";
+    type: string;
+    html: string;
+    context?: unknown;
+};
+type GenerateJSON = (html: string, extensions: Extensions) => unknown;
 export declare function composeDocument(request: RenderDocumentRequest, registry: DocumentRegistry): Promise<RenderResult>;
+export declare function parseDocument(request: ParseDocumentRequest, registry: DocumentRegistry, generateJSON?: GenerateJSON): Promise<ParseResult>;
+export declare function createParseDocument(generateJSON: GenerateJSON): (request: ParseDocumentRequest, registry: DocumentRegistry) => Promise<ParseResult>;

package/dist/document.js

@@ -35,6 +35,27 @@ function collectDroppedNodes(document, extensions) {
     walk(document.content);
     return [...counts].map(([type, count]) => ({ type, count }));
 }
+async function resolveRenderer(type, registry) {
+    const loader = registry[type];
+    if (!loader)
+        throw new Error(`React email document renderer not found: ${type}`);
+    const renderer = typeof loader === "function" ? await loader() : loader;
+    if (typeof renderer.buildExtensions !== "function") {
+        throw new Error(`React email document renderer must export a buildExtensions function: ${type}`);
+    }
+    return renderer;
+}
+async function loadGenerateJSON() {
+    try {
+        const mod = (await import(/* @vite-ignore */ "@tiptap/html"));
+        if (typeof mod.generateJSON === "function")
+            return mod.generateJSON;
+    }
+    catch (error) {
+        throw new Error(`@tiptap/html and happy-dom are required to parse HTML documents; install both packages before calling parse (${error instanceof Error ? error.message : "module load failed"})`);
+    }
+    throw new Error("@tiptap/html is missing the expected generateJSON export; check the installed version");
+}
 export async function composeDocument(request, registry) {
     // Fail legibly if the optional editor peers are present but their shape shifted.
     if (typeof composeReactEmail !== "function" ||
@@ -42,13 +63,7 @@ export async function composeDocument(request, registry) {
         typeof getSchema !== "function") {
         throw new Error("@react-email/editor or @tiptap/core is missing expected exports (composeReactEmail/resolveExtensions/getSchema); check the installed versions");
     }
-    const loader = registry[request.type];
-    if (!loader)
-        throw new Error(`React email document renderer not found: ${request.type}`);
-    const renderer = typeof loader === "function" ? await loader() : loader;
-    if (typeof renderer.buildExtensions !== "function") {
-        throw new Error(`React email document renderer must export a buildExtensions function: ${request.type}`);
-    }
+    const renderer = await resolveRenderer(request.type, registry);
     const document = renderer.transformDocument?.(request.document, request.context) ?? request.document;
     const extensions = resolveExtensions(renderer.buildExtensions(request.context));
     const schema = getSchema(extensions);
@@ -67,3 +82,15 @@ export async function composeDocument(request, registry) {
     const { html, text } = await composeReactEmail(params);
     return warnings.length > 0 ? { html, text, warnings } : { html, text };
 }
+export async function parseDocument(request, registry, generateJSON) {
+    const parseHTML = generateJSON ?? (await loadGenerateJSON());
+    const renderer = await resolveRenderer(request.type, registry);
+    const extensions = resolveExtensions(renderer.buildExtensions(request.context));
+    const schema = getSchema(extensions);
+    const parsed = parseHTML(request.html, extensions);
+    const document = schema.nodeFromJSON(parsed).toJSON();
+    return { document };
+}
+export function createParseDocument(generateJSON) {
+    return (request, registry) => parseDocument(request, registry, generateJSON);
+}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 const DEFAULT_IGNORE = ["**/_*", "**/_*/**"];
 const DEFAULT_EMAIL_PATH = "app/javascript/emails";
 const DEFAULT_EMAIL_EXTENSIONS = [".tsx", ".jsx"];
@@ -14,6 +15,16 @@ const CONFIG_SYMBOL = Symbol.for("react-email-rails.config");
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite");
 const OUT_DIR = "tmp/react-email-rails";
 const BUNDLE_FILE = "emails.js";
+const require = createRequire(import.meta.url);
+// happy-dom (pulled in by @tiptap/html when parsing) depends on `ws`, which guards
+// optional native-addon requires behind these env flags. A standalone (noExternal)
+// build would otherwise try to bundle the uninstalled `bufferutil`/`utf-8-validate`
+// and fail at load. Setting the flags lets Rollup tree-shake those require branches
+// away; ws uses its pure-JS implementation, which is all the HTML parser needs.
+const WS_NATIVE_ADDON_OPT_OUT = {
+    "process.env.WS_NO_BUFFER_UTIL": "'1'",
+    "process.env.WS_NO_UTF_8_VALIDATE": "'1'",
+};
 function normalizeSource(option, defaultPath, defaultExtensions) {
     const source = typeof option === "string" ? { path: option } : (option ?? {});
     const path = (source.path ?? defaultPath).replace(/^\/|\/$/g, "");
@@ -38,6 +49,17 @@ function normalizeSource(option, defaultPath, defaultExtensions) {
     const globArg = JSON.stringify(globPatterns.length === 1 ? globPatterns[0] : globPatterns);
     return { path, extensions, ignore, root, globArg };
 }
+function optionalPeersAvailable(specifiers) {
+    return specifiers.every((specifier) => {
+        try {
+            require.resolve(specifier);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export function reactEmailRails(options = {}) {
     const emailSource = normalizeSource(options.emails, DEFAULT_EMAIL_PATH, DEFAULT_EMAIL_EXTENSIONS);
     const documentSource = options.documents === undefined || options.documents === false
@@ -60,12 +82,17 @@ export function reactEmailRails(options = {}) {
             handler(id) {
                 if (id === RESOLVED_SERVER) {
                     const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`];
-                    // Imported only here, so the editor stays out of the email build graph when off.
-                    if (documentSource)
-                        lines.push(`import { composeDocument } from "react-email-rails/document"`);
+                    const parserPeersAvailable = documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"]);
+                    if (documentSource) {
+                        lines.push(parserPeersAvailable
+                            ? `import { composeDocument, createParseDocument } from "react-email-rails/document"`
+                            : `import { composeDocument, parseDocument } from "react-email-rails/document"`);
+                        if (parserPeersAvailable)
+                            lines.push(`import { generateJSON } from "@tiptap/html"`);
+                    }
                     lines.push(`const modules = import.meta.glob(${emailSource.globArg})`, `const extensions = ${JSON.stringify(emailSource.extensions)}`, `const registry = Object.create(null)`, `for (const path in modules) {`, `  const extension = extensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`, `  registry[toComponentName(path, ${JSON.stringify(emailSource.root)}, extension)] = modules[path]`, `}`);
                     if (documentSource) {
-                        lines.push(`const documentModules = import.meta.glob(${documentSource.globArg})`, `const documentExtensions = ${JSON.stringify(documentSource.extensions)}`, `const documentRegistry = Object.create(null)`, `for (const path in documentModules) {`, `  const extension = documentExtensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`, `  documentRegistry[toComponentName(path, ${JSON.stringify(documentSource.root)}, extension)] = documentModules[path]`, `}`, `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument })`);
+                        lines.push(`const documentModules = import.meta.glob(${documentSource.globArg})`, `const documentExtensions = ${JSON.stringify(documentSource.extensions)}`, `const documentRegistry = Object.create(null)`, `for (const path in documentModules) {`, `  const extension = documentExtensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`, `  documentRegistry[toComponentName(path, ${JSON.stringify(documentSource.root)}, extension)] = documentModules[path]`, `}`, `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument, parse: ${parserPeersAvailable ? "createParseDocument(generateJSON)" : "parseDocument"} })`);
                     }
                     else {
                         lines.push(`export const run = () => serve(registry)`);
@@ -88,7 +115,9 @@ export function reactEmailRails(options = {}) {
             return {
                 environments: {
                     [EMAIL_ENVIRONMENT]: {
-                        ...(standalone && env.command === "build" ? { resolve: { noExternal: true } } : {}),
+                        ...(standalone && env.command === "build"
+                            ? { resolve: { noExternal: true }, define: WS_NATIVE_ADDON_OPT_OUT }
+                            : {}),
                         build: {
                             ssr: true,
                             outDir: OUT_DIR,

package/dist/runtime.d.ts

@@ -24,6 +24,12 @@ export type RenderDocumentRequest = {
     context?: unknown;
     preview?: string | null;
 };
+export type ParseDocumentRequest = {
+    kind: "parse";
+    type: string;
+    html: string;
+    context?: unknown;
+};
 export type DroppedNode = {
     type: string;
     count: number;
@@ -31,9 +37,13 @@ export type DroppedNode = {
 export type RenderResult = RenderedEmail & {
     warnings?: DroppedNode[];
 };
+export type ParseResult = {
+    document: unknown;
+};
 export type DocumentSupport<Registry = unknown> = {
     registry: Registry;
     compose: (request: RenderDocumentRequest, registry: Registry) => Promise<RenderResult>;
+    parse: (request: ParseDocumentRequest, registry: Registry) => Promise<ParseResult>;
 };
 export type EmailRenderOptions = {
     html?: ReactEmailRenderOptions;

package/dist/runtime.js

@@ -22,16 +22,25 @@ function isDocumentRequest(request) {
         typeof request === "object" &&
         request.kind === "document");
 }
+function isParseRequest(request) {
+    return (request !== null &&
+        typeof request === "object" &&
+        request.kind === "parse");
+}
 function isHealthRequest(request) {
     return request !== null && typeof request === "object" && "health" in request;
 }
-// Requests without a document kind are component renders, preserving the email path.
 async function renderRequest(request, registry, documents) {
     if (isDocumentRequest(request)) {
         if (!documents)
             throw new Error("React email document rendering is not enabled");
         return documents.compose(request, documents.registry);
     }
+    if (isParseRequest(request)) {
+        if (!documents)
+            throw new Error("React email document rendering is not enabled");
+        return documents.parse(request, documents.registry);
+    }
     return renderEmail(request, registry);
 }
 export async function serve(registry, documents = null) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0";
-export declare const RENDER_PROTOCOL_VERSION = 2;
+export declare const VERSION = "0.3.0";
+export declare const RENDER_PROTOCOL_VERSION = 3;

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.2.0";
-export const RENDER_PROTOCOL_VERSION = 2;
+export const VERSION = "0.3.0";
+export const RENDER_PROTOCOL_VERSION = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-email-rails",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Build and send emails using React and Rails",
   "license": "MIT",
   "type": "module",
@@ -64,6 +64,8 @@
     "@react-email/editor": "^1.5",
     "@react-email/render": "^2.0.0",
     "@tiptap/core": "^3",
+    "@tiptap/html": "^3",
+    "happy-dom": "^20.8.9",
     "react": "^18.0 || ^19.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
@@ -73,15 +75,24 @@
     },
     "@tiptap/core": {
       "optional": true
+    },
+    "@tiptap/html": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@react-email/editor": "^1.5.3",
     "@react-email/render": "^2.0.8",
     "@tiptap/core": "^3",
+    "@tiptap/html": "^3",
+    "@tiptap/pm": "^3",
     "@types/node": "^25.9.1",
     "@types/react": "^19.2.15",
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "happy-dom": "^20.8.9",
     "oxfmt": "^0.52.0",
     "oxlint": "^1.67.0",
     "oxlint-tsgolint": "^0.23.0",

package/src/document.ts

@@ -4,7 +4,7 @@ import { EmailTheming } from "@react-email/editor/plugins"
 import { getSchema, resolveExtensions, type Extensions } from "@tiptap/core"
 import type { Editor } from "@tiptap/core"
 
-import type { DroppedNode, RenderResult } from "./runtime.js"
+import type { DroppedNode, ParseResult, RenderResult } from "./runtime.js"
 
 export type { DroppedNode }
 
@@ -61,6 +61,47 @@ export type RenderDocumentRequest = {
   preview?: string | null
 }
 
+export type ParseDocumentRequest = {
+  kind: "parse"
+  type: string
+  html: string
+  context?: unknown
+}
+
+type GenerateJSON = (html: string, extensions: Extensions) => unknown
+
+async function resolveRenderer(
+  type: string,
+  registry: DocumentRegistry,
+): Promise<DocumentRenderer> {
+  const loader = registry[type]
+  if (!loader) throw new Error(`React email document renderer not found: ${type}`)
+
+  const renderer = typeof loader === "function" ? await loader() : loader
+  if (typeof renderer.buildExtensions !== "function") {
+    throw new Error(`React email document renderer must export a buildExtensions function: ${type}`)
+  }
+
+  return renderer
+}
+
+async function loadGenerateJSON(): Promise<GenerateJSON> {
+  try {
+    const mod = (await import(/* @vite-ignore */ "@tiptap/html")) as {
+      generateJSON?: unknown
+    }
+    if (typeof mod.generateJSON === "function") return mod.generateJSON as GenerateJSON
+  } catch (error) {
+    throw new Error(
+      `@tiptap/html and happy-dom are required to parse HTML documents; install both packages before calling parse (${error instanceof Error ? error.message : "module load failed"})`,
+    )
+  }
+
+  throw new Error(
+    "@tiptap/html is missing the expected generateJSON export; check the installed version",
+  )
+}
+
 export async function composeDocument(
   request: RenderDocumentRequest,
   registry: DocumentRegistry,
@@ -76,15 +117,7 @@ export async function composeDocument(
     )
   }
 
-  const loader = registry[request.type]
-  if (!loader) throw new Error(`React email document renderer not found: ${request.type}`)
-
-  const renderer = typeof loader === "function" ? await loader() : loader
-  if (typeof renderer.buildExtensions !== "function") {
-    throw new Error(
-      `React email document renderer must export a buildExtensions function: ${request.type}`,
-    )
-  }
+  const renderer = await resolveRenderer(request.type, registry)
 
   const document =
     renderer.transformDocument?.(request.document, request.context) ?? request.document
@@ -108,3 +141,24 @@ export async function composeDocument(
   const { html, text } = await composeReactEmail(params)
   return warnings.length > 0 ? { html, text, warnings } : { html, text }
 }
+
+export async function parseDocument(
+  request: ParseDocumentRequest,
+  registry: DocumentRegistry,
+  generateJSON?: GenerateJSON,
+): Promise<ParseResult> {
+  const parseHTML = generateJSON ?? (await loadGenerateJSON())
+  const renderer = await resolveRenderer(request.type, registry)
+  const extensions = resolveExtensions(renderer.buildExtensions(request.context))
+  const schema = getSchema(extensions)
+
+  const parsed = parseHTML(request.html, extensions)
+  const document = schema.nodeFromJSON(parsed).toJSON()
+
+  return { document }
+}
+
+export function createParseDocument(generateJSON: GenerateJSON) {
+  return (request: ParseDocumentRequest, registry: DocumentRegistry): Promise<ParseResult> =>
+    parseDocument(request, registry, generateJSON)
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module"
+
 import type { ConfigEnv, Plugin, UserConfig } from "vite"
 
 export type EmailsOption =
@@ -64,6 +66,17 @@ const CONFIG_SYMBOL = Symbol.for("react-email-rails.config")
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite")
 const OUT_DIR = "tmp/react-email-rails"
 const BUNDLE_FILE = "emails.js"
+const require = createRequire(import.meta.url)
+
+// happy-dom (pulled in by @tiptap/html when parsing) depends on `ws`, which guards
+// optional native-addon requires behind these env flags. A standalone (noExternal)
+// build would otherwise try to bundle the uninstalled `bufferutil`/`utf-8-validate`
+// and fail at load. Setting the flags lets Rollup tree-shake those require branches
+// away; ws uses its pure-JS implementation, which is all the HTML parser needs.
+const WS_NATIVE_ADDON_OPT_OUT = {
+  "process.env.WS_NO_BUFFER_UTIL": "'1'",
+  "process.env.WS_NO_UTF_8_VALIDATE": "'1'",
+}
 
 function normalizeSource(
   option: EmailsOption | undefined,
@@ -101,6 +114,17 @@ function normalizeSource(
   return { path, extensions, ignore, root, globArg }
 }
 
+function optionalPeersAvailable(specifiers: string[]): boolean {
+  return specifiers.every((specifier) => {
+    try {
+      require.resolve(specifier)
+      return true
+    } catch {
+      return false
+    }
+  })
+}
+
 export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
   const emailSource = normalizeSource(options.emails, DEFAULT_EMAIL_PATH, DEFAULT_EMAIL_EXTENSIONS)
   const documentSource =
@@ -129,10 +153,17 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       handler(id) {
         if (id === RESOLVED_SERVER) {
           const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`]
+          const parserPeersAvailable =
+            documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"])
 
-          // Imported only here, so the editor stays out of the email build graph when off.
-          if (documentSource)
-            lines.push(`import { composeDocument } from "react-email-rails/document"`)
+          if (documentSource) {
+            lines.push(
+              parserPeersAvailable
+                ? `import { composeDocument, createParseDocument } from "react-email-rails/document"`
+                : `import { composeDocument, parseDocument } from "react-email-rails/document"`,
+            )
+            if (parserPeersAvailable) lines.push(`import { generateJSON } from "@tiptap/html"`)
+          }
 
           lines.push(
             `const modules = import.meta.glob(${emailSource.globArg})`,
@@ -153,7 +184,7 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
               `  const extension = documentExtensions.find((extension) => path.endsWith(extension)) ?? path.slice(path.lastIndexOf("."))`,
               `  documentRegistry[toComponentName(path, ${JSON.stringify(documentSource.root)}, extension)] = documentModules[path]`,
               `}`,
-              `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument })`,
+              `export const run = () => serve(registry, { registry: documentRegistry, compose: composeDocument, parse: ${parserPeersAvailable ? "createParseDocument(generateJSON)" : "parseDocument"} })`,
             )
           } else {
             lines.push(`export const run = () => serve(registry)`)
@@ -179,7 +210,9 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       return {
         environments: {
           [EMAIL_ENVIRONMENT]: {
-            ...(standalone && env.command === "build" ? { resolve: { noExternal: true } } : {}),
+            ...(standalone && env.command === "build"
+              ? { resolve: { noExternal: true }, define: WS_NATIVE_ADDON_OPT_OUT }
+              : {}),
             build: {
               ssr: true,
               outDir: OUT_DIR,

package/src/runtime.ts

@@ -33,6 +33,13 @@ export type RenderDocumentRequest = {
   preview?: string | null
 }
 
+export type ParseDocumentRequest = {
+  kind: "parse"
+  type: string
+  html: string
+  context?: unknown
+}
+
 // A document node type that rendered to nothing, with how many times it occurred.
 export type DroppedNode = { type: string; count: number }
 
@@ -40,11 +47,14 @@ export type DroppedNode = { type: string; count: number }
 // extension rendered them). Component renders never carry warnings.
 export type RenderResult = RenderedEmail & { warnings?: DroppedNode[] }
 
+export type ParseResult = { document: unknown }
+
 // Injected by the generated server module when documents are enabled, so `serve`
 // renders documents without importing the editor module or its peer types.
 export type DocumentSupport<Registry = unknown> = {
   registry: Registry
   compose: (request: RenderDocumentRequest, registry: Registry) => Promise<RenderResult>
+  parse: (request: ParseDocumentRequest, registry: Registry) => Promise<ParseResult>
 }
 
 type ProtocolMetadata = {
@@ -87,21 +97,33 @@ function isDocumentRequest(request: unknown): request is RenderDocumentRequest {
   )
 }
 
+function isParseRequest(request: unknown): request is ParseDocumentRequest {
+  return (
+    request !== null &&
+    typeof request === "object" &&
+    (request as { kind?: unknown }).kind === "parse"
+  )
+}
+
 function isHealthRequest(request: unknown): request is HealthRequest {
   return request !== null && typeof request === "object" && "health" in request
 }
 
-// Requests without a document kind are component renders, preserving the email path.
 async function renderRequest<Registry>(
-  request: RenderRequest | RenderDocumentRequest,
+  request: RenderRequest | RenderDocumentRequest | ParseDocumentRequest,
   registry: EmailRegistry,
   documents: DocumentSupport<Registry> | null,
-): Promise<RenderResult> {
+): Promise<RenderResult | ParseResult> {
   if (isDocumentRequest(request)) {
     if (!documents) throw new Error("React email document rendering is not enabled")
     return documents.compose(request, documents.registry)
   }
 
+  if (isParseRequest(request)) {
+    if (!documents) throw new Error("React email document rendering is not enabled")
+    return documents.parse(request, documents.registry)
+  }
+
   return renderEmail(request, registry)
 }
 
@@ -121,7 +143,10 @@ export async function serve<Registry = unknown>(
 
   const write = isolateStdout()
   try {
-    const request = JSON.parse(await readStdin()) as RenderRequest | RenderDocumentRequest
+    const request = JSON.parse(await readStdin()) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
     write(
       JSON.stringify({
         ...(await renderRequest(request, registry, documents)),
@@ -186,7 +211,11 @@ async function writePersistentResponse<Registry>(
   write: (chunk: string) => boolean,
 ): Promise<void> {
   try {
-    const request = JSON.parse(line) as RenderRequest | RenderDocumentRequest | HealthRequest
+    const request = JSON.parse(line) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
+      | HealthRequest
     if (isHealthRequest(request)) {
       write(`${JSON.stringify(okResponse())}\n`)
       return

package/src/version.ts

@@ -1,2 +1,2 @@
-export const VERSION = "0.2.0"
-export const RENDER_PROTOCOL_VERSION = 2
+export const VERSION = "0.3.0"
+export const RENDER_PROTOCOL_VERSION = 3