react-email-rails 0.6.0 → 0.7.0

package/bin/build.mjs

@@ -51,8 +51,6 @@ const { userConfig, plugin, vite } = await loadReactEmailRailsConfig({
   configLoader,
 })
 
-// Same isolation as the dev renderer: keep component resolve/transforms but leave unrelated
-// app plugins out of the email environment so their hooks can't break SSR output.
 const builder = await createBuilder(
   isolatedViteConfig(userConfig, vite, {
     root: root ?? userConfig.root,

package/bin/dev.mjs

@@ -31,14 +31,12 @@ const divertStdout = () => {
   }
 }
 
-// Load only this plugin and aliases; host dev-server plugins have global side effects.
 const restoreStdout = divertStdout()
 const { userConfig, plugin, vite } = await loadReactEmailRailsConfig({
   command: "serve",
   mode: "development",
 })
 
-// Forward only component resolve/compile config, so dev rendering stays close to the build.
 const server = await createServer(
   isolatedViteConfig(userConfig, vite, {
     configFile: false,
@@ -50,7 +48,6 @@ const server = await createServer(
   }),
 )
 
-// Render through the same `email` environment as the production build, so the two match.
 const environment = server.environments.email
 if (!isRunnableDevEnvironment(environment)) {
   await server.close()
@@ -59,7 +56,6 @@ if (!isRunnableDevEnvironment(environment)) {
 
 try {
   const { run } = await environment.runner.import("virtual:react-email-rails/server")
-  // Restore before run(): serve() re-isolates stdout with its own protocol writer.
   restoreStdout()
   await run()
 } finally {

package/bin/shared.mjs

@@ -2,10 +2,8 @@ import { loadConfigFromFile, mergeConfig } from "vite"
 
 import { RENDER_PROTOCOL_VERSION, VERSION } from "../dist/version.js"
 
-// Wire contract: must match the Symbol.for(...) keys in src/index.ts.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config")
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite")
-// Must mirror ReactEmailRailsViteOptions in src/index.ts and the option list in README.md.
 const EMAIL_VITE_CONFIG_KEYS = [
   "assetsInclude",
   "css",
@@ -17,12 +15,15 @@ const EMAIL_VITE_CONFIG_KEYS = [
   "resolve",
 ]
 
-// Emit the version/protocol handshake and exit on --health. Shared by the build and dev bins.
 export function exitIfHealthCheck() {
   if (!process.argv.includes("--health")) return
 
   process.stdout.write(
-    JSON.stringify({ ok: true, protocolVersion: RENDER_PROTOCOL_VERSION, packageVersion: VERSION }),
+    JSON.stringify({
+      ok: true,
+      protocolVersion: RENDER_PROTOCOL_VERSION,
+      packageVersion: VERSION,
+    }),
   )
   process.exit(0)
 }

package/dist/document.js

@@ -2,13 +2,9 @@ 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 or the match isn't an
-// EmailNode; mirror that here so warnings catch the silent case (in-schema node, no email renderer).
 function collectDroppedNodes(document, extensions) {
     const byName = new Map();
     for (const extension of extensions)
@@ -69,11 +65,7 @@ async function loadRenderMarkdown() {
     }
     throw new Error("marked is missing the expected parse export; check the installed version");
 }
-// The schema whitelists nodes and attributes but never validates URI protocols, so a
-// javascript:/data: href on a link or button reaches content_json unchecked. Allow only safe schemes.
 const ALLOWED_URI_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
-// Characters browsers ignore when resolving a scheme (so "java\tscript:" runs as javascript:).
-// Built numerically to keep the source free of literal control characters.
 const URI_IGNORED_RANGES = [
     [0x00, 0x20],
     [0xa0, 0xa0],
@@ -89,12 +81,9 @@ const URI_IGNORED_CHARS = new RegExp("[" +
     URI_IGNORED_RANGES.map(([lo, hi]) => escapeCodePoint(lo) + "-" + escapeCodePoint(hi)).join("") +
     "]", "g");
 function hasAllowedUriScheme(uri) {
-    // No scheme → relative/anchor/query; nothing to neutralize.
     const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(uri.replace(URI_IGNORED_CHARS, ""))?.[1];
     return scheme === undefined || ALLOWED_URI_SCHEMES.has(scheme.toLowerCase());
 }
-// Blank disallowed hrefs (link marks and nodes like button) in place; the tree is fresh
-// toJSON() output, so mutation is safe.
 function neutralizeUnsafeUris(value) {
     if (Array.isArray(value)) {
         for (const item of value)
@@ -111,7 +100,6 @@ function neutralizeUnsafeUris(value) {
     neutralizeUnsafeUris(node.marks);
     neutralizeUnsafeUris(node.content);
 }
-// Both inputs converge on HTML: markdown is rendered first, then parsed like any HTML.
 async function resolveHtmlInput(request, dependencies) {
     const hasHtml = request.html !== undefined;
     const hasMarkdown = request.markdown !== undefined;
@@ -125,7 +113,6 @@ async function resolveHtmlInput(request, dependencies) {
     return request.html;
 }
 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") {
@@ -136,15 +123,12 @@ export async function composeDocument(request, registry) {
     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);
@@ -162,7 +146,6 @@ export async function parseDocument(request, registry, dependencies = {}) {
     return { document };
 }
 export function createParseDocument(generateJSON, renderMarkdown) {
-    // Omit renderMarkdown entirely when unset; exactOptionalPropertyTypes forbids passing `undefined`.
     const dependencies = renderMarkdown === undefined ? { generateJSON } : { generateJSON, renderMarkdown };
     return (request, registry) => parseDocument(request, registry, dependencies);
 }

package/dist/index.js

@@ -9,18 +9,12 @@ const VIRTUAL_MAIN = "virtual:react-email-rails/main";
 const RESOLVED_SERVER = `\0${VIRTUAL_SERVER}`;
 const RESOLVED_MAIN = `\0${VIRTUAL_MAIN}`;
 const VIRTUAL_MODULE_PATTERN = /virtual:react-email-rails\/(?:server|main)$/;
-// The dedicated build environment that emits the server-side email bundle.
 export const EMAIL_ENVIRONMENT = "email";
-// Wire contract: must match the Symbol.for(...) keys the bins read in bin/shared.mjs.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config");
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite");
-// Must match Ruby's Configuration::BUNDLE_PATH (check_version_sync.rb asserts it).
 const OUT_DIR = "tmp/react-email-rails";
 const BUNDLE_FILE = "emails.js";
 const require = createRequire(import.meta.url);
-// happy-dom (via @tiptap/html) pulls in `ws`, which guards optional native-addon requires behind
-// these flags. Setting them lets a standalone (noExternal) build tree-shake the uninstalled
-// bufferutil/utf-8-validate requires away; ws's pure-JS path 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'",
@@ -49,6 +43,13 @@ function normalizeSource(option, defaultPath, defaultExtensions) {
     const globArg = JSON.stringify(globPatterns.length === 1 ? globPatterns[0] : globPatterns);
     return { path, extensions, ignore, root, globArg };
 }
+function normalizePath(path) {
+    return path.replace(/\\/g, "/");
+}
+function isWithinSource(file, root, relativeDir) {
+    const base = `${normalizePath(root).replace(/\/+$/, "")}/${relativeDir}/`;
+    return normalizePath(file).startsWith(base);
+}
 function optionalPeersAvailable(specifiers) {
     return specifiers.every((specifier) => {
         try {
@@ -65,6 +66,7 @@ export function reactEmailRails(options = {}) {
     const documentSource = options.documents === undefined || options.documents === false
         ? null
         : normalizeSource(options.documents === true ? undefined : options.documents, DEFAULT_DOCUMENT_PATH, DEFAULT_DOCUMENT_EXTENSIONS);
+    const liveReloadDirs = [emailSource.path, documentSource?.path].filter((path) => Boolean(path));
     const standalone = options.standalone ?? true;
     const plugin = {
         name: "react-email-rails",
@@ -83,7 +85,6 @@ export function reactEmailRails(options = {}) {
                 if (id === RESOLVED_SERVER) {
                     const lines = [`import { buildRegistry, serve } from "react-email-rails/runtime"`];
                     const parserPeersAvailable = documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"]);
-                    // Markdown parsing layers `marked` on top of the HTML parser peers.
                     const markdownPeerAvailable = parserPeersAvailable && optionalPeersAvailable(["marked"]);
                     if (documentSource) {
                         lines.push(parserPeersAvailable
@@ -109,10 +110,16 @@ export function reactEmailRails(options = {}) {
                 }
             },
         },
+        hotUpdate(options) {
+            const root = options.server.config.root;
+            if (!liveReloadDirs.some((dir) => isWithinSource(options.file, root, dir)))
+                return;
+            if (this.environment.name !== "client")
+                return;
+            this.environment.hot.send({ type: "full-reload" });
+            return [];
+        },
         config(_config, env) {
-            // Dedicated `email` build environment: the react-email-rails-build bin builds it with an
-            // isolated plugin stack so host plugins can't break email SSR. Standalone builds inline
-            // Node deps (so Rails images need no node_modules); dev keeps them external for the runner.
             return {
                 environments: {
                     [EMAIL_ENVIRONMENT]: {

package/dist/runtime.js

@@ -20,8 +20,14 @@ export async function renderEmail(request, registry) {
     const mod = typeof loader === "function" ? await loader() : loader;
     const element = React.createElement(mod.default, request.props ?? {});
     return {
-        html: await render(element, { ...request.renderOptions?.html, plainText: false }),
-        text: await render(element, { ...request.renderOptions?.text, plainText: true }),
+        html: await render(element, {
+            ...request.renderOptions?.html,
+            plainText: false,
+        }),
+        text: await render(element, {
+            ...request.renderOptions?.text,
+            plainText: true,
+        }),
     };
 }
 function isDocumentRequest(request) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.7.0";
 export declare const RENDER_PROTOCOL_VERSION = 3;

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.6.0";
+export const VERSION = "0.7.0";
 export const RENDER_PROTOCOL_VERSION = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-email-rails",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Build and send emails using React and Rails",
   "license": "MIT",
   "type": "module",
@@ -50,10 +50,11 @@
     "check:version": "ruby ../scripts/check_version_sync.rb",
     "lint": "oxlint src test bin",
     "format": "oxfmt src test bin",
+    "check:format": "oxfmt --check src test bin",
     "typecheck": "tsgo -p tsconfig.json --noEmit",
     "test": "vitest run",
     "sync:version": "ruby ../scripts/sync_version.rb",
-    "ci": "pnpm run check:version && pnpm build && pnpm lint && pnpm typecheck && pnpm test",
+    "ci": "pnpm run check:version && pnpm run check:format && pnpm build && pnpm lint && pnpm typecheck && pnpm test",
     "prepack": "pnpm run sync:version && pnpm build",
     "prepublishOnly": "pnpm run check:version"
   },

package/src/document.ts

@@ -12,7 +12,6 @@ import type {
   RenderResult,
 } from "./runtime.js"
 
-// Re-exported from runtime.ts (the single source) to keep react-email-rails/document's surface.
 export type { DroppedNode, ParseDocumentRequest, RenderDocumentRequest }
 
 export type DocumentRenderer = {
@@ -21,16 +20,12 @@ export type DocumentRenderer = {
   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 or the match isn't an
-// EmailNode; mirror that here so warnings catch the silent case (in-schema node, 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)
@@ -62,7 +57,6 @@ export type DocumentRegistry = Record<string, DocumentLoader>
 type GenerateJSON = (html: string, extensions: Extensions) => unknown
 type RenderMarkdown = (markdown: string) => string | Promise<string>
 
-// Bound at build time by createParseDocument when the peers are bundled; lazy-loaded otherwise.
 type ParseDependencies = {
   generateJSON?: GenerateJSON
   renderMarkdown?: RenderMarkdown
@@ -120,12 +114,8 @@ async function loadRenderMarkdown(): Promise<RenderMarkdown> {
   throw new Error("marked is missing the expected parse export; check the installed version")
 }
 
-// The schema whitelists nodes and attributes but never validates URI protocols, so a
-// javascript:/data: href on a link or button reaches content_json unchecked. Allow only safe schemes.
 const ALLOWED_URI_SCHEMES: ReadonlySet<string> = new Set(["http", "https", "mailto", "tel"])
 
-// Characters browsers ignore when resolving a scheme (so "java\tscript:" runs as javascript:).
-// Built numerically to keep the source free of literal control characters.
 const URI_IGNORED_RANGES: ReadonlyArray<readonly [number, number]> = [
   [0x00, 0x20],
   [0xa0, 0xa0],
@@ -145,14 +135,11 @@ const URI_IGNORED_CHARS = new RegExp(
 )
 
 function hasAllowedUriScheme(uri: string): boolean {
-  // No scheme → relative/anchor/query; nothing to neutralize.
   const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(uri.replace(URI_IGNORED_CHARS, ""))?.[1]
 
   return scheme === undefined || ALLOWED_URI_SCHEMES.has(scheme.toLowerCase())
 }
 
-// Blank disallowed hrefs (link marks and nodes like button) in place; the tree is fresh
-// toJSON() output, so mutation is safe.
 function neutralizeUnsafeUris(value: unknown): void {
   if (Array.isArray(value)) {
     for (const item of value) neutralizeUnsafeUris(item)
@@ -176,7 +163,6 @@ function neutralizeUnsafeUris(value: unknown): void {
   neutralizeUnsafeUris(node.content)
 }
 
-// Both inputs converge on HTML: markdown is rendered first, then parsed like any HTML.
 async function resolveHtmlInput(
   request: ParseDocumentRequest,
   dependencies: ParseDependencies,
@@ -199,7 +185,6 @@ 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" ||
@@ -218,8 +203,6 @@ export async function composeDocument(
   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 },
@@ -227,11 +210,10 @@ export async function composeDocument(
     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 }
 }
 
@@ -243,18 +225,17 @@ export async function parseDocument(
   const renderer = await resolveRenderer(request.type, registry)
   const extensions = resolveExtensions(renderer.buildExtensions(request.context))
   const schema = getSchema(extensions)
-
   const html = await resolveHtmlInput(request, dependencies)
   const parseHTML = dependencies.generateJSON ?? (await loadGenerateJSON())
   const parsed = parseHTML(html, extensions)
   const document = schema.nodeFromJSON(parsed).toJSON()
+
   neutralizeUnsafeUris(document)
 
   return { document }
 }
 
 export function createParseDocument(generateJSON: GenerateJSON, renderMarkdown?: RenderMarkdown) {
-  // Omit renderMarkdown entirely when unset; exactOptionalPropertyTypes forbids passing `undefined`.
   const dependencies: ParseDependencies =
     renderMarkdown === undefined ? { generateJSON } : { generateJSON, renderMarkdown }
   return (request: ParseDocumentRequest, registry: DocumentRegistry): Promise<ParseResult> =>

package/src/index.ts

@@ -12,7 +12,6 @@ export type EmailsOption =
 
 export type ReactEmailRailsOptions = {
   emails?: EmailsOption
-  // Editor document renderers, discovered like emails. Off by default.
   documents?: EmailsOption | boolean
   standalone?: boolean
   vite?: ReactEmailRailsViteOptions
@@ -59,19 +58,13 @@ const RESOLVED_SERVER = `\0${VIRTUAL_SERVER}`
 const RESOLVED_MAIN = `\0${VIRTUAL_MAIN}`
 const VIRTUAL_MODULE_PATTERN = /virtual:react-email-rails\/(?:server|main)$/
 
-// The dedicated build environment that emits the server-side email bundle.
 export const EMAIL_ENVIRONMENT = "email"
-// Wire contract: must match the Symbol.for(...) keys the bins read in bin/shared.mjs.
 const CONFIG_SYMBOL = Symbol.for("react-email-rails.config")
 const VITE_CONFIG_SYMBOL = Symbol.for("react-email-rails.vite")
-// Must match Ruby's Configuration::BUNDLE_PATH (check_version_sync.rb asserts it).
 const OUT_DIR = "tmp/react-email-rails"
 const BUNDLE_FILE = "emails.js"
 const require = createRequire(import.meta.url)
 
-// happy-dom (via @tiptap/html) pulls in `ws`, which guards optional native-addon requires behind
-// these flags. Setting them lets a standalone (noExternal) build tree-shake the uninstalled
-// bufferutil/utf-8-validate requires away; ws's pure-JS path 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'",
@@ -113,6 +106,15 @@ function normalizeSource(
   return { path, extensions, ignore, root, globArg }
 }
 
+function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/")
+}
+
+function isWithinSource(file: string, root: string, relativeDir: string): boolean {
+  const base = `${normalizePath(root).replace(/\/+$/, "")}/${relativeDir}/`
+  return normalizePath(file).startsWith(base)
+}
+
 function optionalPeersAvailable(specifiers: string[]): boolean {
   return specifiers.every((specifier) => {
     try {
@@ -134,6 +136,9 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
           DEFAULT_DOCUMENT_PATH,
           DEFAULT_DOCUMENT_EXTENSIONS,
         )
+  const liveReloadDirs = [emailSource.path, documentSource?.path].filter((path): path is string =>
+    Boolean(path),
+  )
   const standalone = options.standalone ?? true
 
   const plugin: Plugin = {
@@ -154,7 +159,6 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
           const lines = [`import { buildRegistry, serve } from "react-email-rails/runtime"`]
           const parserPeersAvailable =
             documentSource && optionalPeersAvailable(["@tiptap/html", "happy-dom"])
-          // Markdown parsing layers `marked` on top of the HTML parser peers.
           const markdownPeerAvailable = parserPeersAvailable && optionalPeersAvailable(["marked"])
 
           if (documentSource) {
@@ -191,10 +195,16 @@ export function reactEmailRails(options: ReactEmailRailsOptions = {}): Plugin {
       },
     },
 
+    hotUpdate(options) {
+      const root = options.server.config.root
+      if (!liveReloadDirs.some((dir) => isWithinSource(options.file, root, dir))) return
+      if (this.environment.name !== "client") return
+
+      this.environment.hot.send({ type: "full-reload" })
+      return []
+    },
+
     config(_config, env: ConfigEnv) {
-      // Dedicated `email` build environment: the react-email-rails-build bin builds it with an
-      // isolated plugin stack so host plugins can't break email SSR. Standalone builds inline
-      // Node deps (so Rails images need no node_modules); dev keeps them external for the runner.
       return {
         environments: {
           [EMAIL_ENVIRONMENT]: {

package/src/runtime.ts

@@ -47,7 +47,6 @@ export type RenderDocumentRequest = {
   preview?: string | null
 }
 
-// Exactly one of `html` or `markdown` is set.
 export type ParseDocumentRequest = {
   kind: "parse"
   type: string
@@ -108,8 +107,14 @@ export async function renderEmail(
   const element = React.createElement(mod.default, request.props ?? {})
 
   return {
-    html: await render(element, { ...request.renderOptions?.html, plainText: false }),
-    text: await render(element, { ...request.renderOptions?.text, plainText: true }),
+    html: await render(element, {
+      ...request.renderOptions?.html,
+      plainText: false,
+    }),
+    text: await render(element, {
+      ...request.renderOptions?.text,
+      plainText: true,
+    }),
   }
 }
 

package/src/version.ts

@@ -1,2 +1,2 @@
-export const VERSION = "0.6.0"
+export const VERSION = "0.7.0"
 export const RENDER_PROTOCOL_VERSION = 3