react-email-rails 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5d324a8d629ad252aa11946478dd3b610c78920675bb027aedabf8c96c36239
-  data.tar.gz: eaa690f2caecb96ef322bac6e587bb1dbf2bfe51e9c601a8b1b9dceb4d43d7a8
+  metadata.gz: 8de13aced1b8b88a622cdc40577ec17c80ad457cee75ea57266dc248e5355416
+  data.tar.gz: d42cacd94f77a32ccf75d72b5e8c19506549902c64617a723c6617e0bc613a58
 SHA512:
-  metadata.gz: ca696714d6b95038f96fc579c8040fb9eaf6e98b213ddf42ba7ab92fdb49e5ab8d1dc3bb6b8a095d8fc91573314df6f4ae06136c4af41f3ec9cf66ea2bd22c85
-  data.tar.gz: 77c513dfda5a19d5296396433d4adb79e198cffcda518311e4fe5f780efb19f532baba3743dd0b0d08928528eece7d74047280f0d3bde34a89a565ab06ddd975
+  metadata.gz: 1fbbbb75215e8b4b77de4d4c15e533348e2b7195196d5b9401541596e24507b3c046ca8f74998f20b76f9fbf6d9b67d8c0ec29a86af3aaa64e0b1b70bece4c85
+  data.tar.gz: 5e7025b1552256c5d1b2fd01a911c7d941b2fd41aa6cd94ddd646fbeb79713888dd6dc13785ff71c66cadb9362877e2abe4715855630813314e7073f509ccccc

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents (Tiptap/ProseMirror JSON) to HTML and text, the server analog of the editor's client-side `composeReactEmail` export.
+- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`. It is off by default; the editor packages stay out of the email render path and build graph unless it is enabled.
+- Report document nodes that render to nothing (a node whose extension is not an email renderer) as non-fatal warnings — on the result (`rendered.warnings`) and the `render.react-email-rails` instrumentation payload (`payload[:warnings]`) — so silently dropped content is detectable.
+- 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 a uniform `(error, **context)` shape, where `context` carries `kind:` (`"email"`/`"document"`) and either `component:` (emails) or `type:` (documents). Update `->(error, component:) { ... }` callbacks to `->(error, **context) { ... }`.
+
 ## 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,138 @@ 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
+```
+
+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,          # Tiptap JSON, e.g. 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.
+
+**Keys:** `context` is key-transformed exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)). The **`document` is passed through verbatim** — its keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and are never transformed.
+
+`render_options` does not apply to documents; `composeReactEmail` controls its own rendering.
+
+### 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 +510,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"` or `"document"`) plus the identifier — `component:` for emails, `type:` for documents. Accept `**context` so one handler covers both render kinds:
 
 ```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"` or `"document"`), the `component` name (email) or `type` (document), and, on success, the rendered HTML size in `html_bytes`. 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 +543,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,7 @@ 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")
       end,
     ))
   rescue JSON::ParserError => e

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -8,10 +8,11 @@ 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).
+  def initialize(payload:, label:)
+    @payload = payload
+    @label = label
   end
 
   def render
@@ -20,7 +21,7 @@ class ReactEmailRails::RenderModes::Subprocess
 
   private
 
-  attr_reader(:component, :props, :render_options)
+  attr_reader(:payload, :label)
 
   def run
     result = capture(payload_json)
@@ -28,7 +29,7 @@ class ReactEmailRails::RenderModes::Subprocess
 
     body = JSON.parse(result.stdout)
     validate_response!(body)
-    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s)
+    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
   rescue JSON::ParserError => e
     raise(render_error("render process returned invalid JSON: #{e.message}"))
   rescue KeyError => e
@@ -52,17 +53,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
@@ -93,7 +83,14 @@ class ReactEmailRails::RenderModes::Subprocess
     raise(render_error("render process returned an invalid response: text must be a string")) if body.key?("text") && !body["text"].is_a?(String)
   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 = 2
 
   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.2.0"
 end

data/lib/react_email_rails.rb

@@ -37,13 +37,33 @@ 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, component:)
+      configuration.on_render_error&.call(e, kind: "document", type:)
       raise
     end
 
@@ -55,5 +75,20 @@ 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 |rendered|
+          payload[:html_bytes] = rendered.html.bytesize
+          payload[:warnings] = rendered.warnings if rendered.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.2.0
 platform: ruby
 authors:
 - Supertape