react-email-rails 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5d324a8d629ad252aa11946478dd3b610c78920675bb027aedabf8c96c36239
-  data.tar.gz: eaa690f2caecb96ef322bac6e587bb1dbf2bfe51e9c601a8b1b9dceb4d43d7a8
+  metadata.gz: 52da00b9618d5b217b66af2598edf2a25fa9d0850447bfc95d8637c778837583
+  data.tar.gz: 84bcdbd09672b293b85d65bbde9779c0d0d2c2c282dd83e72cc2412d38150c6b
 SHA512:
-  metadata.gz: ca696714d6b95038f96fc579c8040fb9eaf6e98b213ddf42ba7ab92fdb49e5ab8d1dc3bb6b8a095d8fc91573314df6f4ae06136c4af41f3ec9cf66ea2bd22c85
-  data.tar.gz: 77c513dfda5a19d5296396433d4adb79e198cffcda518311e4fe5f780efb19f532baba3743dd0b0d08928528eece7d74047280f0d3bde34a89a565ab06ddd975
+  metadata.gz: b9ce2a8643e90776bee1f37c9758fd9d853465d37b73184e0ebdeb20a87e33d9d686354b1a8256cb3bb4887221d25b7c14c9b6733d905c04e86f3fa2d1e06cc7
+  data.tar.gz: 1257c29d6639ed5a1559d23d64316bea2c6ccf075b365e816dc0bfd41cb996003e466dbabe97bc50aa9b736e2a45e81e083cd908791f91d8d94f13b239e65f67

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0
+
+- Add `ReactEmailRails.parse` to convert semantic HTML into a canonical `@react-email/editor` document using a renderer's extensions.
+- Add `@tiptap/html` and `happy-dom` as optional peer dependencies, required only when calling `parse`; compose-only document rendering does not require them.
+- Bump the render protocol to 3 (the renderer now accepts parse requests). The Ruby gem and npm package must be upgraded together, as before.
+
+## 0.2.0
+
+- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents to HTML and text.
+- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`.
+- Report document nodes that render to nothing as non-fatal warnings on the result and instrumentation payload.
+- Add `@react-email/editor` and `@tiptap/core` as optional peer dependencies (only required when rendering documents).
+- Bump the render protocol to 2 (the renderer now accepts document requests). The Ruby gem and npm package must be upgraded together, as before.
+- **Breaking:** `on_render_error` callbacks now receive `(error, **context)` with `kind:` plus `component:` for emails or `type:` for documents.
+
 ## 0.1.3
 
 - Remove the `verify_render_on_boot` configuration option, which only logged on failure and duplicated the render-time `ReactEmailRails::RenderError`.

data/README.md

@@ -1,3 +1,5 @@
+![React Email + Rails](react-email-rails.png)
+
 # React Email + Rails
 
 Build and send emails using React and Rails — a seamless integration between [React Email](https://react.email) and [Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html).
@@ -10,6 +12,7 @@ Build and send emails using React and Rails — a seamless integration between [
 - [Requirements](#requirements)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
+- [Editor](#editor)
 - [Configuration](#configuration)
 - [Deployment](#deployment)
 - [Development](#development)
@@ -41,6 +44,7 @@ React Email Rails automatically renders both HTML and plain-text versions from t
 - Vite 7 or 8
 - React 18 or 19
 - `@react-email/render` 2.x
+- For [rendering editor documents](#editor) (optional): `@react-email/editor` 1.5+ and `@tiptap/core` 3.x
 
 > We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite with Rails.
 
@@ -291,6 +295,174 @@ export default function Welcome() {
 
 See [Component Names](#component-names) for how shared `_` files are handled.
 
+## Editor
+
+Alongside named components, the gem can render a [@react-email/editor](https://react.email/docs/editor) document — the Tiptap/ProseMirror JSON a visual editor produces — to HTML and text on the server.
+
+React Email exposes [composeReactEmail](https://react.email/docs/editor/api-reference/compose-react-email) for this, but only from the browser, with a live editor instance from the export panel. `ReactEmailRails.compose` is the server analog: it rebuilds what `composeReactEmail` needs headlessly (no DOM, no live editor) from the stored document and the extensions you declare, then calls the same function. So `compose` is to the editor what `render` is to a component.
+
+This is opt-in. The editor packages are optional peer dependencies and stay out of the email render path until you enable it.
+
+### Setup
+
+Install the editor packages:
+
+```sh
+npm i @react-email/editor @tiptap/core
+```
+
+To also parse HTML into documents with [`parse`](#parsing-html-into-a-document), add `@tiptap/html` and its server DOM, `happy-dom`:
+
+```sh
+npm i @tiptap/html happy-dom
+```
+
+Enable the `documents` option in your Vite config:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite"
+import { reactEmailRails } from "react-email-rails"
+
+export default defineConfig({
+  plugins: [reactEmailRails({ documents: true })],
+})
+```
+
+`documents: true` enables it with defaults (`app/javascript/documents`, `.ts`/`.tsx` extensions). Like `emails`, it also accepts a directory string or `{ path, extension, ignore }`. See [Plugin Options](#plugin-options).
+
+### Document Renderers
+
+A document doesn't carry the editor configuration it was authored with, so a headless renderer has to be told which extensions a given document needs. Each file under the documents directory is a **document renderer** — the editor-side analog of an email component — and its name is resolved from the directory layout just like [component names](#component-names) (so `broadcast` maps to `app/javascript/documents/broadcast.ts`).
+
+```ts
+// app/javascript/documents/broadcast.ts
+
+import { StarterKit } from "@react-email/editor/extensions"
+import { EmailTheming } from "@react-email/editor/plugins"
+
+// Required: the Tiptap extensions the document was authored with.
+export function buildExtensions() {
+  return [StarterKit, EmailTheming]
+}
+```
+
+A renderer can export two optional hooks:
+
+| Export | Required | Description |
+|--------|----------|-------------|
+| `buildExtensions(context)` | Yes | Returns the Tiptap extension list for the document. |
+| `transformDocument(document, context)` | No | Returns a rewritten document before rendering — for example, to inject header/footer nodes that aren't persisted in the stored document. |
+| `getPreview(context)` | No | Returns inbox preview text when the `compose` call doesn't pass one. |
+
+`context` is the optional data you pass to `compose` (see below). Use it to vary extensions, transforms, or preview text per render.
+
+```ts
+// app/javascript/documents/broadcast.ts
+
+import { StarterKit } from "@react-email/editor/extensions"
+import { EmailTheming } from "@react-email/editor/plugins"
+
+export function buildExtensions(context) {
+  return [StarterKit, EmailTheming]
+}
+
+// Inject a branded header after the persisted theme node, wherever it sits.
+export function transformDocument(document, context) {
+  const header = {
+    type: "heading",
+    attrs: { level: 1 },
+    content: [{ type: "text", text: context.brandName }],
+  }
+  // Find globalContent and insert after it, rather than assuming a position, so
+  // the theme node is preserved.
+  const themeIndex = document.content.findIndex((node) => node.type === "globalContent")
+  const at = themeIndex + 1
+  return {
+    ...document,
+    content: [...document.content.slice(0, at), header, ...document.content.slice(at)],
+  }
+}
+
+export function getPreview(context) {
+  return context.previewText
+}
+```
+
+> **Match the extensions to the document.** `composeReactEmail` renders any node whose extension isn't registered as `null`, so a document that uses a node your `buildExtensions` omits will silently drop that content. Return the same extension list the document was authored with.
+
+> **Keep the theme node.** The editor persists its theme in a `globalContent` node and `EmailTheming` reads it back when rendering. If you reshape the document in `transformDocument`, preserve that node.
+
+### Composing a Document
+
+Call `ReactEmailRails.compose` with the renderer `type`, the stored document, and optional `context`/`preview`:
+
+```ruby
+broadcast = Broadcast.find(params[:id])
+
+rendered = ReactEmailRails.compose(
+  type: "broadcast",
+  document: broadcast.body,          # a Hash in Tiptap's shape, e.g. from a jsonb column
+  context: { brand_name: "Acme", preview_text: broadcast.subject },
+  preview: broadcast.subject,        # optional; falls back to getPreview(context)
+)
+
+rendered.html # => "<!DOCTYPE html>..."
+rendered.text # => "ACME\n\n..."
+```
+
+It returns the same `RenderedEmail` (`html`/`text`) as `render`, runs through the same [render modes](#render-modes), and raises `ReactEmailRails::RenderError` on failure. Documents don't go through Action Mailer — broadcasts and the like usually have their own delivery path — so deliver `rendered.html`/`rendered.text` however your app sends mail.
+
+**The document is a `Hash`.** You pass and store it as a plain Ruby `Hash` with string keys — what a jsonb column hands back, and what [`parse`](#parsing-html-into-a-document) returns. "Tiptap JSON" names the document's *shape* (and the format it's serialized to over the wire to the renderer), not the Ruby type; `compose` accepts any object that responds to `as_json`, but a `Hash` is the norm.
+
+**Keys:** the document's keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and **passed through verbatim** — never transformed. Only `context` is key-transformed, camelized exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)).
+
+`render_options` does not apply to documents; `composeReactEmail` controls its own rendering.
+
+### Parsing HTML into a Document
+
+`ReactEmailRails.parse` converts semantic HTML into the same document `Hash` shape the editor stores, using the selected renderer's extensions. This needs the `@tiptap/html` and `happy-dom` packages (see [Setup](#setup)).
+
+```ruby
+document = ReactEmailRails.parse(
+  type: "broadcast",                 # the same renderer type compose uses
+  html: params[:body_html],          # the HTML the caller sent
+  context: { brand_name: "Acme" },   # optional; reaches buildExtensions, like compose
+)
+
+broadcast.update!(body: document)    # persist the Hash (e.g. to a jsonb column)
+```
+
+Later, render the stored document like any other:
+
+```ruby
+rendered = ReactEmailRails.compose(type: "broadcast", document: broadcast.body)
+```
+
+`parse` returns a plain Ruby `Hash` with string keys, normalized through the renderer's schema. It uses the same [render modes](#render-modes) as `compose` and raises `ReactEmailRails::RenderError` on failure. `context` is key-transformed like component props; the HTML is sent verbatim.
+
+What this means in practice:
+
+- HTML maps to a node only when an extension defines how to parse it. Unknown elements, inline styles, and classes may be dropped or flattened.
+- Editor-only constructs such as custom email nodes and the persisted `globalContent` theme node do not round-trip from plain HTML.
+- If you already have the document `Hash`, pass it to `compose` directly.
+
+### Debugging Dropped Content
+
+The most common integration bug is an extension/document mismatch. A node whose type is **missing from `buildExtensions` entirely** raises `ReactEmailRails::RenderError` (it can't be parsed) — loud and safe. The quiet case is a node that *is* in the schema but whose extension does not render to email (a plain Tiptap node rather than an email one): `composeReactEmail` renders it as nothing, with no error.
+
+`compose` reports those dropped node types so the silent case isn't silent. They appear both on the result as `rendered.warnings` and on the [`render.react-email-rails`](#instrumentation) instrumentation event as `payload[:warnings]` — an array of `{ type:, count: }`. The editor's own non-rendering nodes (the `globalContent` theme node and similar) are excluded, so a non-empty `warnings` means real content was lost. Subscribe to the event to alert on it — or refuse to send:
+
+```ruby
+ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
+  warnings = event.payload[:warnings]
+  raise "dropped #{warnings.sum { _1[:count] }} node(s): #{warnings.map { _1[:type] }.join(", ")}" if warnings
+end
+```
+
+If content is missing, confirm `buildExtensions` returns the **same** extensions the document was authored with — the editor's `StarterKit` plus every custom node and plugin in use — and, if you reshape the document in `transformDocument`, that you preserved the `globalContent` theme node. Treat a mismatch as data or version skew: pinning a document's renderer `type` to the extension set it was created with, and versioning that set, avoids drift.
+
 ## Configuration
 
 Configuration is handled primarily on the Rails side, though there are some Vite options to be aware of.
@@ -374,19 +546,19 @@ end
 
 #### Error Reporting
 
-Use `on_render_error` to report failures before the exception is re-raised:
+Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error and a `context` of `kind:` (`"email"`, `"document"`, or `"parse"`) plus the identifier — `component:` for emails, `type:` for documents and parse requests. Accept `**context` so one handler covers every render kind:
 
 ```ruby
 ReactEmailRails.configure do |config|
-  config.on_render_error = ->(error, component:) {
-    Rails.error.report(error, context: { component: })
+  config.on_render_error = ->(error, **context) {
+    Rails.error.report(error, context:)
   }
 end
 ```
 
 #### Instrumentation
 
-Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries the `component` name and, on success, the rendered HTML size in `html_bytes`:
+Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries a `kind` (`"email"`, `"document"`, or `"parse"`), the `component` name (email) or `type` (document and parse), and, on a successful render, the rendered HTML size in `html_bytes` (omitted for `parse`, which returns a document rather than HTML). Document renders that drop content also include `warnings` (see [Debugging Dropped Content](#debugging-dropped-content)):
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
@@ -407,6 +579,10 @@ In development and production, the isolated renderer loads the `reactEmailRails(
 | `emails.path` | `"app/javascript/emails"` | Directory containing email components |
 | `emails.extension` | `[".tsx", ".jsx"]` | Component extension, or an array of extensions |
 | `emails.ignore` | `["**/_*", "**/_*/**"]` | Glob patterns ignored under `emails.path` |
+| `documents` | `false` (off) | Enable [editor document rendering](#editor). `true`, a path string, or `{ path, extension, ignore }` |
+| `documents.path` | `"app/javascript/documents"` | Directory containing document renderers |
+| `documents.extension` | `[".ts", ".tsx"]` | Renderer extension, or an array of extensions |
+| `documents.ignore` | `["**/_*", "**/_*/**"]` | Glob patterns ignored under `documents.path` |
 | `standalone` | `true` | Inline production email bundle dependencies |
 | `vite` | `{}` | Extra email-only Vite config for compilation and resolution |
 

data/SECURITY.md

@@ -3,3 +3,7 @@
 Please report security issues privately by emailing hi@supertape.com.
 
 Do not open a public GitHub issue for suspected vulnerabilities. Include the affected version, a minimal reproduction when possible, and any relevant deployment details.
+
+## Rendering editor documents
+
+`ReactEmailRails.compose` renders an `@react-email/editor` document (Tiptap/ProseMirror JSON) server-side. Treat that document as untrusted input: it is typically authored in a visual editor and stored, then rendered later. The renderer only dispatches to the extensions you register for that document type, and React Email escapes rendered output, but URL and asset sanitization inside your custom extensions (links, image sources, button hrefs) remains your application's responsibility. Validate or sanitize those values where you build extensions or transform the document.

data/lib/react_email_rails/render_modes/persistent/server.rb

@@ -80,6 +80,8 @@ class ReactEmailRails::RenderModes::Persistent::Server
       }.tap do |body|
         body[:html] = response["html"] if response.key?("html")
         body[:text] = response["text"] if response.key?("text")
+        body[:warnings] = response["warnings"] if response.key?("warnings")
+        body[:document] = response["document"] if response.key?("document")
       end,
     ))
   rescue JSON::ParserError => e

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -8,10 +8,14 @@ class ReactEmailRails::RenderModes::Subprocess
     end
   end
 
-  def initialize(component:, props:, render_options: {})
-    @component = component
-    @props = props
-    @render_options = render_options
+  # Payload-agnostic transport: the caller builds and serializes the payload.
+  # `label` identifies the render in error messages (component name or document type).
+  # `response` selects how the renderer's reply is interpreted: `:email` builds a
+  # RenderedEmail (render/compose), `:document` returns the parsed document (parse).
+  def initialize(payload:, label:, response: :email)
+    @payload = payload
+    @label = label
+    @response = response
   end
 
   def render
@@ -20,15 +24,15 @@ class ReactEmailRails::RenderModes::Subprocess
 
   private
 
-  attr_reader(:component, :props, :render_options)
+  attr_reader(:payload, :label, :response)
 
   def run
     result = capture(payload_json)
     raise(render_error(error_message(result.stderr, result.status))) unless result.status.success?
 
     body = JSON.parse(result.stdout)
-    validate_response!(body)
-    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s)
+    validate_metadata!(body)
+    build_result(body)
   rescue JSON::ParserError => e
     raise(render_error("render process returned invalid JSON: #{e.message}"))
   rescue KeyError => e
@@ -52,17 +56,6 @@ class ReactEmailRails::RenderModes::Subprocess
     ReactEmailRails.configuration.render_timeout
   end
 
-  def payload
-    @payload ||= begin
-      payload = {
-        component:,
-        props: ReactEmailRails.configuration.send(:serialize_props, props),
-      }
-      payload[:renderOptions] = render_options if render_options.present?
-      payload
-    end
-  end
-
   def payload_json
     @payload_json ||= JSON.generate(payload)
   end
@@ -85,15 +78,41 @@ class ReactEmailRails::RenderModes::Subprocess
     raise(render_error("email bundle not found at #{bundle_path.inspect}; run react-email-rails-build before rendering React emails"))
   end
 
-  def validate_response!(body)
-    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body))) unless ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+  def validate_metadata!(body)
+    return if ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+
+    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body)))
+  end
+
+  def build_result(body)
+    response == :document ? build_document(body) : build_rendered_email(body)
+  end
 
+  def build_rendered_email(body)
     raise(KeyError.new(key: "html")) unless body.key?("html")
     raise(render_error("render process returned an invalid response: html must be a string")) unless body["html"].is_a?(String)
     raise(render_error("render process returned an invalid response: text must be a string")) if body.key?("text") && !body["text"].is_a?(String)
+
+    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
+  end
+
+  def build_document(body)
+    raise(KeyError.new(key: "document")) unless body.key?("document")
+
+    document = body.fetch("document")
+    raise(render_error("parse process returned an invalid response: document must be an object")) unless document.is_a?(Hash)
+
+    document
+  end
+
+  def warnings_from(body)
+    warnings = body["warnings"]
+    return [] unless warnings.is_a?(Array)
+
+    warnings.filter_map { |warning| warning.transform_keys(&:to_sym) if warning.is_a?(Hash) }
   end
 
   def render_error(message)
-    ReactEmailRails::RenderError.new("React Email render failed for #{component}: #{message}")
+    ReactEmailRails::RenderError.new("React Email render failed for #{label}: #{message}")
   end
 end

data/lib/react_email_rails/render_protocol.rb

@@ -1,5 +1,5 @@
 module ReactEmailRails
-  RENDER_PROTOCOL_VERSION = 1
+  RENDER_PROTOCOL_VERSION = 3
 
   module RenderProtocol
     extend(self)

data/lib/react_email_rails/rendered_email.rb

@@ -1,3 +1,9 @@
 module ReactEmailRails
-  RenderedEmail = Data.define(:html, :text)
+  # `warnings` carries non-fatal renderer warnings (e.g. document nodes dropped
+  # because no extension rendered them); empty for component renders.
+  RenderedEmail = Data.define(:html, :text, :warnings) do
+    def initialize(html:, text:, warnings: [])
+      super
+    end
+  end
 end

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.1.3"
+  VERSION = "0.3.0"
 end

data/lib/react_email_rails.rb

@@ -37,13 +37,50 @@ module ReactEmailRails
     end
 
     def render(component:, props:, render_options: configuration.resolve_render_options)
-      ActiveSupport::Notifications.instrument("render.react-email-rails", component:) do |payload|
-        configuration.resolved_render_mode.new(component:, props:, render_options:).render.tap do |rendered|
-          payload[:html_bytes] = rendered.html.bytesize
-        end
+      payload = { component:, props: serialized_props(props) }
+      payload[:renderOptions] = render_options if render_options.present?
+
+      instrument(kind: "email", component:) do
+        configuration.resolved_render_mode.new(payload:, label: component).render
+      end
+    rescue ReactEmailRails::RenderError => e
+      configuration.on_render_error&.call(e, kind: "email", component:)
+      raise
+    end
+
+    # Render an @react-email/editor document (Tiptap JSON) to HTML+text. The document
+    # is sent verbatim (its keys are structural); only context is key-transformed, like props.
+    def compose(type:, document:, context: {}, preview: nil)
+      payload = {
+        kind: "document",
+        type:,
+        document: document.as_json,
+        context: serialized_props(context),
+        preview:,
+      }
+
+      instrument(kind: "document", type:) do
+        configuration.resolved_render_mode.new(payload:, label: type).render
+      end
+    rescue ReactEmailRails::RenderError => e
+      configuration.on_render_error&.call(e, kind: "document", type:)
+      raise
+    end
+
+    # Parse HTML into an editor document Hash using the renderer's extensions.
+    def parse(type:, html:, context: {})
+      payload = {
+        kind: "parse",
+        type:,
+        html: html.to_s,
+        context: serialized_props(context),
+      }
+
+      instrument(kind: "parse", type:) do
+        configuration.resolved_render_mode.new(payload:, label: type, response: :document).render
       end
     rescue ReactEmailRails::RenderError => e
-      configuration.on_render_error&.call(e, component:)
+      configuration.on_render_error&.call(e, kind: "parse", type:)
       raise
     end
 
@@ -55,5 +92,22 @@ module ReactEmailRails
     rescue StandardError
       false
     end
+
+    private
+
+    def serialized_props(value)
+      configuration.send(:serialize_props, value)
+    end
+
+    def instrument(**metadata)
+      ActiveSupport::Notifications.instrument("render.react-email-rails", **metadata) do |payload|
+        yield.tap do |result|
+          next unless result.respond_to?(:html)
+
+          payload[:html_bytes] = result.html.bytesize
+          payload[:warnings] = result.warnings if result.warnings.present?
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Supertape