react-email-rails 0.1.3 → 0.3.0

package/dist/document.d.ts

@@ -0,0 +1,27 @@
+import { type Extensions } from "@tiptap/core";
+import type { DroppedNode, ParseResult, RenderResult } from "./runtime.js";
+export type { DroppedNode };
+export type DocumentRenderer = {
+    buildExtensions: (context: unknown) => Extensions;
+    transformDocument?: (document: unknown, context: unknown) => unknown;
+    getPreview?: (context: unknown) => string | null;
+};
+export type DocumentLoader = DocumentRenderer | (() => Promise<DocumentRenderer>);
+export type DocumentRegistry = Record<string, DocumentLoader>;
+export type RenderDocumentRequest = {
+    kind: "document";
+    type: string;
+    document: unknown;
+    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

@@ -0,0 +1,96 @@
+import { EmailNode, composeReactEmail } from "@react-email/editor/core";
+import { StarterKit } from "@react-email/editor/extensions";
+import { EmailTheming } from "@react-email/editor/plugins";
+import { getSchema, resolveExtensions } from "@tiptap/core";
+// Editor-bundled structural nodes render to null by design. Derive the list from
+// the installed editor package so warning filtering tracks version changes.
+const STRUCTURAL_NODE_TYPES = new Set(resolveExtensions([StarterKit, EmailTheming])
+    .filter((extension) => extension.type === "node" && !(extension instanceof EmailNode))
+    .map((extension) => extension.name));
+// composeReactEmail renders a node as null when no extension matches its type or
+// the match is not an EmailNode. Mirror that predicate over the document so
+// warnings report the silent case: an in-schema node with no email renderer.
+function collectDroppedNodes(document, extensions) {
+    const byName = new Map();
+    for (const extension of extensions)
+        byName.set(extension.name, extension);
+    const counts = new Map();
+    const walk = (content) => {
+        if (!Array.isArray(content))
+            return;
+        for (const node of content) {
+            if (!node || typeof node !== "object")
+                continue;
+            const type = node.type;
+            if (typeof type !== "string" || STRUCTURAL_NODE_TYPES.has(type))
+                continue;
+            const extension = byName.get(type);
+            if (!extension || !(extension instanceof EmailNode)) {
+                counts.set(type, (counts.get(type) ?? 0) + 1);
+                continue;
+            }
+            walk(node.content);
+        }
+    };
+    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" ||
+        typeof resolveExtensions !== "function" ||
+        typeof getSchema !== "function") {
+        throw new Error("@react-email/editor or @tiptap/core is missing expected exports (composeReactEmail/resolveExtensions/getSchema); check the installed versions");
+    }
+    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);
+    const warnings = collectDroppedNodes(document, extensions);
+    // The minimal editor composeReactEmail reads, built headless (no DOM, no view).
+    // state.doc is required: EmailTheming finds the globalContent theme node through it.
+    const editor = {
+        getJSON: () => document,
+        extensionManager: { extensions },
+        schema,
+        state: { doc: schema.nodeFromJSON(document) },
+    };
+    // composeReactEmail takes `preview?: string`; omit it rather than pass null.
+    const preview = request.preview ?? renderer.getPreview?.(request.context) ?? null;
+    const params = preview === null ? { editor } : { editor, preview };
+    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.d.ts

@@ -6,6 +6,7 @@ export type EmailsOption = string | {
 };
 export type ReactEmailRailsOptions = {
     emails?: EmailsOption;
+    documents?: EmailsOption | boolean;
     standalone?: boolean;
     vite?: ReactEmailRailsViteOptions;
 };
@@ -14,5 +15,5 @@ export type ReactEmailRailsViteOptions = Pick<UserConfig, "assetsInclude" | "css
 };
 export declare const EMAIL_ENVIRONMENT = "email";
 export declare function reactEmailRails(options?: ReactEmailRailsOptions): Plugin;
-export type { EmailModule, EmailRegistry, EmailRenderOptions, RenderedEmail, RenderRequest, } from "./runtime.js";
+export type { EmailModule, EmailRegistry, EmailRenderOptions, RenderedEmail, RenderRequest, RenderResult, } from "./runtime.js";
 export { RENDER_PROTOCOL_VERSION, VERSION } from "./version.js";

package/dist/index.js

@@ -1,5 +1,9 @@
+import { createRequire } from "node:module";
 const DEFAULT_IGNORE = ["**/_*", "**/_*/**"];
-const DEFAULT_EXTENSIONS = [".tsx", ".jsx"];
+const DEFAULT_EMAIL_PATH = "app/javascript/emails";
+const DEFAULT_EMAIL_EXTENSIONS = [".tsx", ".jsx"];
+const DEFAULT_DOCUMENT_PATH = "app/javascript/documents";
+const DEFAULT_DOCUMENT_EXTENSIONS = [".ts", ".tsx"];
 const VIRTUAL_SERVER = "virtual:react-email-rails/server";
 const VIRTUAL_MAIN = "virtual:react-email-rails/main";
 const RESOLVED_SERVER = `\0${VIRTUAL_SERVER}`;
@@ -11,29 +15,57 @@ 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";
-export function reactEmailRails(options = {}) {
-    const emails = typeof options.emails === "string" ? { path: options.emails } : (options.emails ?? {});
-    const path = (emails.path ?? "app/javascript/emails").replace(/^\/|\/$/g, "");
-    const rawExtensions = emails.extension === undefined
-        ? DEFAULT_EXTENSIONS
-        : Array.isArray(emails.extension)
-            ? emails.extension
-            : [emails.extension];
+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, "");
+    const rawExtensions = source.extension === undefined
+        ? defaultExtensions
+        : Array.isArray(source.extension)
+            ? source.extension
+            : [source.extension];
     const extensions = rawExtensions
         .map((extension) => (extension.startsWith(".") ? extension : `.${extension}`))
         .map((extension, index) => ({ extension, index }))
         .sort((left, right) => right.extension.length - left.extension.length || left.index - right.index)
         .map(({ extension }) => extension);
-    const standalone = options.standalone ?? true;
     const root = `/${path}/`;
     const pattern = extensions.length === 1 ? `${root}**/*${extensions[0]}` : `${root}**/*{${extensions.join(",")}}`;
-    const ignore = emails.ignore === undefined
+    const ignore = source.ignore === undefined
         ? DEFAULT_IGNORE
-        : Array.isArray(emails.ignore)
-            ? emails.ignore
-            : [emails.ignore];
+        : Array.isArray(source.ignore)
+            ? source.ignore
+            : [source.ignore];
     const globPatterns = [pattern, ...ignore.map((glob) => `!${root}${glob}`)];
     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
+        ? null
+        : normalizeSource(options.documents === true ? undefined : options.documents, DEFAULT_DOCUMENT_PATH, DEFAULT_DOCUMENT_EXTENSIONS);
+    const standalone = options.standalone ?? true;
     const plugin = {
         name: "react-email-rails",
         resolveId: {
@@ -49,17 +81,23 @@ export function reactEmailRails(options = {}) {
             filter: { id: VIRTUAL_MODULE_PATTERN },
             handler(id) {
                 if (id === RESOLVED_SERVER) {
-                    return [
-                        `import { serve, toComponentName } from "react-email-rails/runtime"`,
-                        `const modules = import.meta.glob(${globArg})`,
-                        `const extensions = ${JSON.stringify(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(root)}, extension)] = modules[path]`,
-                        `}`,
-                        `export const run = () => serve(registry)`,
-                    ].join("\n");
+                    const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`];
+                    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, parse: ${parserPeersAvailable ? "createParseDocument(generateJSON)" : "parseDocument"} })`);
+                    }
+                    else {
+                        lines.push(`export const run = () => serve(registry)`);
+                    }
+                    return lines.join("\n");
                 }
                 if (id === RESOLVED_MAIN) {
                     return `import { run } from ${JSON.stringify(VIRTUAL_SERVER)}\nrun()\n`;
@@ -77,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,
@@ -94,10 +134,17 @@ export function reactEmailRails(options = {}) {
     };
     const metadata = {
         emails: {
-            path,
-            extensions,
-            ignore,
+            path: emailSource.path,
+            extensions: emailSource.extensions,
+            ignore: emailSource.ignore,
         },
+        ...(documentSource && {
+            documents: {
+                path: documentSource.path,
+                extensions: documentSource.extensions,
+                ignore: documentSource.ignore,
+            },
+        }),
         standalone,
         outDir: OUT_DIR,
         bundleFile: BUNDLE_FILE,

package/dist/runtime.d.ts

@@ -17,10 +17,38 @@ export type RenderedEmail = {
     html: string;
     text: string;
 };
+export type RenderDocumentRequest = {
+    kind: "document";
+    type: string;
+    document: unknown;
+    context?: unknown;
+    preview?: string | null;
+};
+export type ParseDocumentRequest = {
+    kind: "parse";
+    type: string;
+    html: string;
+    context?: unknown;
+};
+export type DroppedNode = {
+    type: string;
+    count: number;
+};
+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;
     text?: ReactEmailRenderOptions;
 };
 export declare function toComponentName(globPath: string, root: string, extension: string): string;
 export declare function renderEmail(request: RenderRequest, registry: EmailRegistry): Promise<RenderedEmail>;
-export declare function serve(registry: EmailRegistry): Promise<void>;
+export declare function serve<Registry = unknown>(registry: EmailRegistry, documents?: DocumentSupport<Registry> | null): Promise<void>;

package/dist/runtime.js

@@ -17,9 +17,35 @@ export async function renderEmail(request, registry) {
         text: await render(element, { ...request.renderOptions?.text, plainText: true }),
     };
 }
-export async function serve(registry) {
+function isDocumentRequest(request) {
+    return (request !== null &&
+        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;
+}
+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) {
     if (process.argv.includes("--persistent")) {
-        await servePersistent(registry, isolateStdout());
+        await servePersistent(registry, documents, isolateStdout());
         return;
     }
     if (process.argv.includes("--health")) {
@@ -29,7 +55,10 @@ export async function serve(registry) {
     const write = isolateStdout();
     try {
         const request = JSON.parse(await readStdin());
-        write(JSON.stringify({ ...(await renderEmail(request, registry)), ...protocolMetadata() }));
+        write(JSON.stringify({
+            ...(await renderRequest(request, registry, documents)),
+            ...protocolMetadata(),
+        }));
     }
     catch (error) {
         process.stderr.write(error instanceof Error ? error.message : "React Email render failed");
@@ -56,7 +85,7 @@ function readStdin() {
         process.stdin.on("error", reject);
     });
 }
-async function servePersistent(registry, write) {
+async function servePersistent(registry, documents, write) {
     process.stdin.setEncoding("utf8");
     let pending = "";
     for await (const chunk of process.stdin) {
@@ -66,19 +95,19 @@ async function servePersistent(registry, write) {
             const line = pending.slice(0, separator);
             pending = pending.slice(separator + 1);
             if (line.trim())
-                await writePersistentResponse(line, registry, write);
+                await writePersistentResponse(line, registry, documents, write);
             separator = pending.indexOf("\n");
         }
     }
 }
-async function writePersistentResponse(line, registry, write) {
+async function writePersistentResponse(line, registry, documents, write) {
     try {
         const request = JSON.parse(line);
-        if ("health" in request) {
+        if (isHealthRequest(request)) {
             write(`${JSON.stringify(okResponse())}\n`);
             return;
         }
-        write(`${JSON.stringify({ ok: true, ...(await renderEmail(request, registry)), ...protocolMetadata() })}\n`);
+        write(`${JSON.stringify({ ok: true, ...(await renderRequest(request, registry, documents)), ...protocolMetadata() })}\n`);
     }
     catch (error) {
         write(`${JSON.stringify({

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.3";
-export declare const RENDER_PROTOCOL_VERSION = 1;
+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.1.3";
-export const RENDER_PROTOCOL_VERSION = 1;
+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.1.3",
+  "version": "0.3.0",
   "description": "Build and send emails using React and Rails",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,10 @@
     "./runtime": {
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js"
+    },
+    "./document": {
+      "types": "./dist/document.d.ts",
+      "import": "./dist/document.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -57,15 +61,38 @@
     "node": ">=20.19.0"
   },
   "peerDependencies": {
+    "@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"
   },
+  "peerDependenciesMeta": {
+    "@react-email/editor": {
+      "optional": true
+    },
+    "@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

@@ -0,0 +1,164 @@
+import { EmailNode, composeReactEmail } from "@react-email/editor/core"
+import { StarterKit } from "@react-email/editor/extensions"
+import { EmailTheming } from "@react-email/editor/plugins"
+import { getSchema, resolveExtensions, type Extensions } from "@tiptap/core"
+import type { Editor } from "@tiptap/core"
+
+import type { DroppedNode, ParseResult, RenderResult } from "./runtime.js"
+
+export type { DroppedNode }
+
+export type DocumentRenderer = {
+  buildExtensions: (context: unknown) => Extensions
+  transformDocument?: (document: unknown, context: unknown) => unknown
+  getPreview?: (context: unknown) => string | null
+}
+
+// Editor-bundled structural nodes render to null by design. Derive the list from
+// the installed editor package so warning filtering tracks version changes.
+const STRUCTURAL_NODE_TYPES: ReadonlySet<string> = new Set(
+  resolveExtensions([StarterKit, EmailTheming])
+    .filter((extension) => extension.type === "node" && !(extension instanceof EmailNode))
+    .map((extension) => extension.name),
+)
+
+// composeReactEmail renders a node as null when no extension matches its type or
+// the match is not an EmailNode. Mirror that predicate over the document so
+// warnings report the silent case: an in-schema node with no email renderer.
+function collectDroppedNodes(document: unknown, extensions: Extensions): DroppedNode[] {
+  const byName = new Map<string, Extensions[number]>()
+  for (const extension of extensions) byName.set(extension.name, extension)
+
+  const counts = new Map<string, number>()
+  const walk = (content: unknown): void => {
+    if (!Array.isArray(content)) return
+    for (const node of content) {
+      if (!node || typeof node !== "object") continue
+      const type = (node as { type?: unknown }).type
+      if (typeof type !== "string" || STRUCTURAL_NODE_TYPES.has(type)) continue
+
+      const extension = byName.get(type)
+      if (!extension || !(extension instanceof EmailNode)) {
+        counts.set(type, (counts.get(type) ?? 0) + 1)
+        continue
+      }
+      walk((node as { content?: unknown }).content)
+    }
+  }
+  walk((document as { content?: unknown }).content)
+
+  return [...counts].map(([type, count]) => ({ type, count }))
+}
+
+export type DocumentLoader = DocumentRenderer | (() => Promise<DocumentRenderer>)
+export type DocumentRegistry = Record<string, DocumentLoader>
+
+export type RenderDocumentRequest = {
+  kind: "document"
+  type: string
+  document: unknown
+  context?: unknown
+  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,
+): Promise<RenderResult> {
+  // Fail legibly if the optional editor peers are present but their shape shifted.
+  if (
+    typeof composeReactEmail !== "function" ||
+    typeof resolveExtensions !== "function" ||
+    typeof getSchema !== "function"
+  ) {
+    throw new Error(
+      "@react-email/editor or @tiptap/core is missing expected exports (composeReactEmail/resolveExtensions/getSchema); check the installed versions",
+    )
+  }
+
+  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)
+  const warnings = collectDroppedNodes(document, extensions)
+
+  // The minimal editor composeReactEmail reads, built headless (no DOM, no view).
+  // state.doc is required: EmailTheming finds the globalContent theme node through it.
+  const editor = {
+    getJSON: () => document,
+    extensionManager: { extensions },
+    schema,
+    state: { doc: schema.nodeFromJSON(document) },
+  } as unknown as Editor
+
+  // composeReactEmail takes `preview?: string`; omit it rather than pass null.
+  const preview = request.preview ?? renderer.getPreview?.(request.context) ?? null
+  const params = preview === null ? { editor } : { editor, preview }
+
+  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 =
@@ -10,6 +12,9 @@ export type EmailsOption =
 
 export type ReactEmailRailsOptions = {
   emails?: EmailsOption
+  // Editor document renderers, discovered like emails. Off by default; pass `true`
+  // to enable with defaults, or a path/options object to customize discovery.
+  documents?: EmailsOption | boolean
   standalone?: boolean
   vite?: ReactEmailRailsViteOptions
 }
@@ -21,19 +26,33 @@ export type ReactEmailRailsViteOptions = Pick<
   oxc?: unknown
 }
 
+type SourceMetadata = {
+  path: string
+  extensions: string[]
+  ignore: string[]
+}
+
 type PluginMetadata = {
-  emails: {
-    path: string
-    extensions: string[]
-    ignore: string[]
-  }
+  emails: SourceMetadata
+  documents?: SourceMetadata
   standalone: boolean
   outDir: string
   bundleFile: string
 }
 
+type Source = {
+  path: string
+  extensions: string[]
+  ignore: string[]
+  root: string
+  globArg: string
+}
+
 const DEFAULT_IGNORE = ["**/_*", "**/_*/**"]
-const DEFAULT_EXTENSIONS = [".tsx", ".jsx"]
+const DEFAULT_EMAIL_PATH = "app/javascript/emails"
+const DEFAULT_EMAIL_EXTENSIONS = [".tsx", ".jsx"]
+const DEFAULT_DOCUMENT_PATH = "app/javascript/documents"
+const DEFAULT_DOCUMENT_EXTENSIONS = [".ts", ".tsx"]
 
 const VIRTUAL_SERVER = "virtual:react-email-rails/server"
 const VIRTUAL_MAIN = "virtual:react-email-rails/main"
@@ -47,17 +66,31 @@ 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)
 
-export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
-  const emails =
-    typeof options.emails === "string" ? { path: options.emails } : (options.emails ?? {})
-  const path = (emails.path ?? "app/javascript/emails").replace(/^\/|\/$/g, "")
+// 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,
+  defaultPath: string,
+  defaultExtensions: string[],
+): Source {
+  const source = typeof option === "string" ? { path: option } : (option ?? {})
+  const path = (source.path ?? defaultPath).replace(/^\/|\/$/g, "")
   const rawExtensions =
-    emails.extension === undefined
-      ? DEFAULT_EXTENSIONS
-      : Array.isArray(emails.extension)
-        ? emails.extension
-        : [emails.extension]
+    source.extension === undefined
+      ? defaultExtensions
+      : Array.isArray(source.extension)
+        ? source.extension
+        : [source.extension]
   const extensions = rawExtensions
     .map((extension) => (extension.startsWith(".") ? extension : `.${extension}`))
     .map((extension, index) => ({ extension, index }))
@@ -65,20 +98,45 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       (left, right) => right.extension.length - left.extension.length || left.index - right.index,
     )
     .map(({ extension }) => extension)
-  const standalone = options.standalone ?? true
 
   const root = `/${path}/`
   const pattern =
     extensions.length === 1 ? `${root}**/*${extensions[0]}` : `${root}**/*{${extensions.join(",")}}`
   const ignore =
-    emails.ignore === undefined
+    source.ignore === undefined
       ? DEFAULT_IGNORE
-      : Array.isArray(emails.ignore)
-        ? emails.ignore
-        : [emails.ignore]
+      : Array.isArray(source.ignore)
+        ? source.ignore
+        : [source.ignore]
   const globPatterns = [pattern, ...ignore.map((glob) => `!${root}${glob}`)]
   const globArg = JSON.stringify(globPatterns.length === 1 ? globPatterns[0] : globPatterns)
 
+  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 =
+    options.documents === undefined || options.documents === false
+      ? null
+      : normalizeSource(
+          options.documents === true ? undefined : options.documents,
+          DEFAULT_DOCUMENT_PATH,
+          DEFAULT_DOCUMENT_EXTENSIONS,
+        )
+  const standalone = options.standalone ?? true
+
   const plugin: Plugin = {
     name: "react-email-rails",
 
@@ -94,17 +152,45 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       filter: { id: VIRTUAL_MODULE_PATTERN },
       handler(id) {
         if (id === RESOLVED_SERVER) {
-          return [
-            `import { serve, toComponentName } from "react-email-rails/runtime"`,
-            `const modules = import.meta.glob(${globArg})`,
-            `const extensions = ${JSON.stringify(extensions)}`,
+          const lines = [`import { serve, toComponentName } from "react-email-rails/runtime"`]
+          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(root)}, extension)] = modules[path]`,
+            `  registry[toComponentName(path, ${JSON.stringify(emailSource.root)}, extension)] = modules[path]`,
             `}`,
-            `export const run = () => serve(registry)`,
-          ].join("\n")
+          )
+
+          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, parse: ${parserPeersAvailable ? "createParseDocument(generateJSON)" : "parseDocument"} })`,
+            )
+          } else {
+            lines.push(`export const run = () => serve(registry)`)
+          }
+
+          return lines.join("\n")
         }
 
         if (id === RESOLVED_MAIN) {
@@ -124,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,
@@ -142,10 +230,17 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
 
   const metadata: PluginMetadata = {
     emails: {
-      path,
-      extensions,
-      ignore,
+      path: emailSource.path,
+      extensions: emailSource.extensions,
+      ignore: emailSource.ignore,
     },
+    ...(documentSource && {
+      documents: {
+        path: documentSource.path,
+        extensions: documentSource.extensions,
+        ignore: documentSource.ignore,
+      },
+    }),
     standalone,
     outDir: OUT_DIR,
     bundleFile: BUNDLE_FILE,
@@ -169,5 +264,6 @@ export type {
   EmailRenderOptions,
   RenderedEmail,
   RenderRequest,
+  RenderResult,
 } from "./runtime.js"
 export { RENDER_PROTOCOL_VERSION, VERSION } from "./version.js"

package/src/runtime.ts

@@ -25,6 +25,38 @@ export type RenderedEmail = {
   text: string
 }
 
+export type RenderDocumentRequest = {
+  kind: "document"
+  type: string
+  document: unknown
+  context?: unknown
+  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 }
+
+// A render result plus any non-fatal warnings (document nodes dropped because no
+// 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 = {
   protocolVersion: number
   packageVersion: string
@@ -57,9 +89,50 @@ export async function renderEmail(
   }
 }
 
-export async function serve(registry: EmailRegistry): Promise<void> {
+function isDocumentRequest(request: unknown): request is RenderDocumentRequest {
+  return (
+    request !== null &&
+    typeof request === "object" &&
+    (request as { kind?: unknown }).kind === "document"
+  )
+}
+
+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
+}
+
+async function renderRequest<Registry>(
+  request: RenderRequest | RenderDocumentRequest | ParseDocumentRequest,
+  registry: EmailRegistry,
+  documents: DocumentSupport<Registry> | null,
+): 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)
+}
+
+export async function serve<Registry = unknown>(
+  registry: EmailRegistry,
+  documents: DocumentSupport<Registry> | null = null,
+): Promise<void> {
   if (process.argv.includes("--persistent")) {
-    await servePersistent(registry, isolateStdout())
+    await servePersistent(registry, documents, isolateStdout())
     return
   }
 
@@ -70,8 +143,16 @@ export async function serve(registry: EmailRegistry): Promise<void> {
 
   const write = isolateStdout()
   try {
-    const request = JSON.parse(await readStdin()) as RenderRequest
-    write(JSON.stringify({ ...(await renderEmail(request, registry)), ...protocolMetadata() }))
+    const request = JSON.parse(await readStdin()) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
+    write(
+      JSON.stringify({
+        ...(await renderRequest(request, registry, documents)),
+        ...protocolMetadata(),
+      }),
+    )
   } catch (error) {
     process.stderr.write(error instanceof Error ? error.message : "React Email render failed")
     process.exitCode = 1
@@ -101,8 +182,9 @@ function readStdin(): Promise<string> {
   })
 }
 
-async function servePersistent(
+async function servePersistent<Registry>(
   registry: EmailRegistry,
+  documents: DocumentSupport<Registry> | null,
   write: (chunk: string) => boolean,
 ): Promise<void> {
   process.stdin.setEncoding("utf8")
@@ -116,26 +198,31 @@ async function servePersistent(
       const line = pending.slice(0, separator)
       pending = pending.slice(separator + 1)
 
-      if (line.trim()) await writePersistentResponse(line, registry, write)
+      if (line.trim()) await writePersistentResponse(line, registry, documents, write)
       separator = pending.indexOf("\n")
     }
   }
 }
 
-async function writePersistentResponse(
+async function writePersistentResponse<Registry>(
   line: string,
   registry: EmailRegistry,
+  documents: DocumentSupport<Registry> | null,
   write: (chunk: string) => boolean,
 ): Promise<void> {
   try {
-    const request = JSON.parse(line) as RenderRequest | HealthRequest
-    if ("health" in request) {
+    const request = JSON.parse(line) as
+      | RenderRequest
+      | RenderDocumentRequest
+      | ParseDocumentRequest
+      | HealthRequest
+    if (isHealthRequest(request)) {
       write(`${JSON.stringify(okResponse())}\n`)
       return
     }
 
     write(
-      `${JSON.stringify({ ok: true, ...(await renderEmail(request, registry)), ...protocolMetadata() })}\n`,
+      `${JSON.stringify({ ok: true, ...(await renderRequest(request, registry, documents)), ...protocolMetadata() })}\n`,
     )
   } catch (error) {
     write(

package/src/version.ts

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