react-email-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ada860a1bfdc970fd871cb2f0d4b89642e42b8641b8d11006ca66e9bf6f452a
-  data.tar.gz: 742b838451251d7b97093077ff9909e3d60441e705a841fed522d1d64df83787
+  metadata.gz: 4bbfbb40c2044856c9061ba2a3c134d07dbd5aa9b58b6cfe3d576d25fe45b4d2
+  data.tar.gz: 7c272a65e71044f813c813b248a48bc69e3a043494ad9f6133ae8c69ab006b24
 SHA512:
-  metadata.gz: 2d7490d1c6bccdd3d7d7eeb5fa0f0a1d6a9888e6090bf560b2d63feab8db4edec448eb7ba6ddbc34134ed9cf1cd34e4a2cb229bf41794c44faefbafe0f98adc0
-  data.tar.gz: c2a55b22219041afe9cc25f00fa5b2ef222f4d45656027c4e971b2666d90a68f02aae4894fc30f3771b3064e41b5c880febead6d79d4cecadb0cb5bd1736e3de
+  metadata.gz: c5b434f0983a8c1280d622203869f535a0c98fb293bcfff3d51d39a8676d730d000b901cb9bcc6b3b478fe633904974798131482e44982140f40e12951ac1423
+  data.tar.gz: 21652f85cc0ee448ec90ffd7b24c4eaf05b892dbe0e83d487777ae57bbcda7a34c46e1b9becad9174838edd0d33919b11aa9efb56cbd520433803c8a3fd82385

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.0
+
+- Add `react_email_share` for sharing props across every `react:` email a mailer renders, mirroring inertia-rails' `inertia_share`. Supports static values, lazy lambdas and blocks (evaluated in the mailer instance), `only`/`except`/`if`/`unless` filters, and subclass inheritance. Per-mail props win over shared props.
+- Shared props merge shallowly by default. Pass `deep_merge: true` to `mail` to merge nested hashes, or set `config.deep_merge_shared_props = true` to make it the default.
+
+## 0.4.1
+
+- `ReactEmailRails.parse` now neutralizes unsafe link/button URI schemes: hrefs whose scheme is not `http`, `https`, `mailto`, or `tel` (e.g. `javascript:`/`data:`) are blanked before they reach the document `Hash`. Scheme detection ignores the whitespace and control characters browsers strip when resolving a scheme, so case- and whitespace-obfuscated payloads are caught too.
+
 ## 0.4.0
 
 - `ReactEmailRails.parse` now accepts `markdown:` as an alternative to `html:`. Markdown is converted to HTML and runs through the same extension-driven parse path, producing the same document `Hash` — handy for agent- or tool-generated content. Pass exactly one of `html:`/`markdown:`.

data/README.md

@@ -1,8 +1,8 @@
-![React Email + Rails](react-email-rails.png)
+![react-email-rails](react-email-rails.png)
 
-# React Email + Rails
+# 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).
+Build and send emails using React and Rails with [React Email](https://react.email) and [Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html).
 
 ## Contents
 
@@ -12,7 +12,6 @@ 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)
@@ -22,19 +21,19 @@ Build and send emails using React and Rails — a seamless integration between [
 
 ## Why
 
-Building HTML emails is painfully archaic. [React Email](https://react.email) is a collection of unstyled components for building emails with React, Tailwind, and TypeScript. This gem brings that power directly into your Rails app. Write emails as React components, send them through Action Mailer, and recipients get automatically generated HTML and text emails.
+Building HTML emails is painfully archaic. [React Email](https://react.email) brings React, Tailwind, and TypeScript to email templates. This gem wires it into Action Mailer so React components deliver as generated HTML and text emails.
 
 ## How
 
 **In development,** the gem renders components live through Vite's dev pipeline, so your emails get the same module resolution and transforms as the rest of your frontend.
 
-**In production,** Rails builds a server-side email bundle during `assets:precompile`. The bundled rake task runs an isolated email-only Vite build, using `reactEmailRails()` in your app's Vite config for discovery and options.
+**In production,** Rails builds a server-side renderer bundle during `assets:precompile` using `reactEmailRails()` in your Vite config for discovery and options.
 
-React Email Rails automatically renders both HTML and plain-text versions from the same component. Delivery, headers, previews, queues, and callbacks all stay normal Action Mailer. If rendering fails, no email is sent and `ReactEmailRails::RenderError` is raised.
+react-email-rails automatically renders both HTML and plain-text versions from the same component. Delivery, headers, previews, queues, and callbacks all stay normal Action Mailer. If rendering fails, no email is sent and `ReactEmailRails::RenderError` is raised.
 
 ## Status
 
-**react-email-rails is pre-1.0.** It's tested in CI across the supported Ruby, Rails, Node, and Vite versions, but it hasn't been battle-tested in high-volume production environments yet, and the API may still change before 1.0. Please [share feedback and report issues](https://github.com/heysupertape/react-email-rails/issues).
+**react-email-rails is pre-1.0.** It was extracted from [XOXO](https://xoxo.email) which is pre-launch, so it hasn't been battle-tested in high-volume production environments yet. It's tested in CI across the supported Ruby, Rails, Node, and Vite versions, but the API may still change before 1.0. Please [share feedback and report issues](https://github.com/heysupertape/react-email-rails/issues).
 
 ## Requirements
 
@@ -67,11 +66,11 @@ bin/rails generate react_email_rails:install
 
 This creates `config/initializers/react_email_rails.rb`, installs missing JavaScript dependencies when it can detect your package manager, adds `reactEmailRails()` to `vite.config.*`, and creates `app/javascript/emails`.
 
-The installed setup follows the normal Rails lifecycle:
+The installed setup then follows the normal Rails lifecycle:
 
 - `bin/rails generate react_email_rails:email ...` creates matching mailers and React components.
-- Development renders through Vite on demand.
-- `bin/rails assets:precompile` builds the production email bundle automatically.
+- `bin/dev` renders through Vite on demand.
+- `bin/rails assets:precompile` builds the production renderer bundle automatically.
 - `bin/rails react_email_rails:build` builds the bundle directly when CI or tests need it.
 
 ### Manual Install
@@ -103,9 +102,7 @@ Generate a mailer and React Email component:
 bin/rails generate react_email_rails:email Account welcome
 ```
 
-The generator follows Rails' mailer generator shape: `NAME [method method]`. It creates `app/mailers/account_mailer.rb`, matching components under your configured React Email directory, plus a mailer preview and test.
-
-The generator reads `emails.path` and `emails.extension` from `reactEmailRails()` when available. Pass flags to override them:
+The generator follows Rails' mailer generator shape: `NAME [method method]`. It creates the mailer, matching React components, a mailer preview, and a test. It reads `emails.path` and `emails.extension` from `reactEmailRails()` when available. Pass flags to override them:
 
 ```sh
 bin/rails generate react_email_rails:email Account welcome --emails-path=app/emails --extension=jsx
@@ -159,11 +156,11 @@ export default function Welcome({ account }: WelcomeProps) {
 
 > [@react-email/components](https://react.email/docs/components/html) provides primitives like `<Button>`, `<Heading>`, `<Tailwind>`, and more.
 
-That's it — it now renders and delivers like any other Action Mailer email.
+That's it. It now renders and delivers like any other Action Mailer email.
 
 ## Usage
 
-Pass data from your mailers and each top-level key becomes a prop on the React component's default export.
+Pass data from your mailer and each top-level key becomes a prop on the component's default export. Our API mirrors [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
 
 ```ruby
 mail react: { foo: "bar" }, ...
@@ -175,9 +172,11 @@ export default function Email({ foo }: { foo: string }) {
 }
 ```
 
-Choose the level of inference you want:
+### Props
+
+Choose the level of inference you want for your props:
 
-### Implicit Component, Instance Props
+#### Implicit Component, Instance Props
 
 ```ruby
 class AccountMailer < ApplicationMailer
@@ -194,7 +193,7 @@ Action Mailer's framework assigns (including `params` and `rendered_format`) are
 
 Without `use_react_instance_props`, `react: true` still infers the component and renders it with no props, which is handy for emails that take no props at all.
 
-### Implicit Component, Explicit Props
+#### Implicit Component, Explicit Props
 
 ```ruby
 mail(
@@ -207,7 +206,7 @@ mail(
 )
 ```
 
-### Explicit Component, Explicit Props
+#### Explicit Component, Explicit Props
 
 ```ruby
 mail(
@@ -221,7 +220,81 @@ mail(
 )
 ```
 
-These forms mirror [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
+### Shared Props
+
+Use `react_email_share` to share data with all of a mailer's emails and subclasses, and it'll be automatically merged with any inline props.
+
+```ruby
+class MarketingMailer < ApplicationMailer
+  # Static value
+  react_email_share app_name: "Acme"
+
+  # Lambda value, evaluated lazily in the mailer instance
+  react_email_share unread_count: -> { current_user&.unread_count }
+
+  # Block, evaluated lazily in the mailer instance
+  react_email_share do
+    { brand: { name: "Acme", url: marketing_url } }
+  end
+end
+```
+
+Per-mail props win over shared props of the same name, so a mailer can always override what it inherits:
+
+```ruby
+mail react: { app_name: "Acme Pro" }, ... # overrides the shared app_name
+```
+
+Shared props apply to all three forms above (`react:` hash, `react: "component", props:`, and `react: true`).
+
+#### Conditional Sharing
+
+Pass any `before_action` filter (`only`, `except`, `if`, `unless`) to scope a share to certain actions:
+
+```ruby
+react_email_share only: [:welcome, :reactivation] do
+  { promotion: current_promotion }
+end
+
+react_email_share if: :user_signed_in? do
+  { user: { name: current_user.name } }
+end
+```
+
+You can also share from inside an action, before calling `mail`:
+
+```ruby
+def welcome
+  react_email_share notice: "Thanks for joining!"
+  mail react: { account: }, to: account.email, subject: "Welcome"
+end
+```
+
+#### Deep Merging
+
+By default shared props are merged shallowly, so a per-mail prop replaces a shared one of the same name outright. Pass `deep_merge: true` to merge nested hashes instead:
+
+```ruby
+react_email_share do
+  { settings: { theme: "light", locale: "en" } }
+end
+
+# Shallow (default): settings => { theme: "dark" }
+mail react: { settings: { theme: "dark" } }, ...
+
+# Deep: settings => { theme: "dark", locale: "en" }
+mail react: { settings: { theme: "dark" } }, deep_merge: true, ...
+```
+
+Set `config.deep_merge_shared_props = true` to make deep merging the default for every email. (See [Configuration](#configuration))
+
+### Prop Serialization
+
+Like `render json:`, `mail react:` accepts any object that responds to `as_json`, including hashes, Active Model objects, and serializers such as [Alba](https://github.com/okuramasafumi/alba) or [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
+
+### Prop Transformation
+
+Prop keys are camelized by default, so `account.plan_name` arrives as `account.planName`. Override `transform_props` in your [configuration](#configuration).
 
 ### Component Names
 
@@ -232,9 +305,9 @@ Component names are inferred from the mailer and action:
 | `AccountMailer#welcome` | `account_mailer/welcome` |
 | `Users::InviteMailer#new_invite` | `users/invite_mailer/new_invite` |
 
-Rails derives `account_mailer` from `AccountMailer` via its `mailer_name`. The default Vite plugin resolves those names under `app/javascript/emails`, so `account_mailer/welcome` maps to `app/javascript/emails/account_mailer/welcome.tsx` or `.jsx`.
+Rails derives `account_mailer` from `AccountMailer` via `mailer_name`. By default, `account_mailer/welcome` resolves to `app/javascript/emails/account_mailer/welcome.tsx` or `.jsx`.
 
-Files and directories starting with `_` are ignored as renderable email entries by default. Use them for shared components such as `_components/email_layout.tsx`; they can still be imported by email components.
+Files and directories starting with `_` are ignored as renderable email entries by default. Use them for shared components such as `_components/email_layout.tsx`. They can still be imported by email components.
 
 Override the inferred name per mail:
 
@@ -244,17 +317,9 @@ mail react: "users/welcome", props: { user: }, to:, subject:
 
 Or override `component_path_resolver` globally in your [configuration](#configuration).
 
-### Prop Serialization
-
-Just like `render json:` in controllers, you can pass any object that responds to `as_json` to `mail react:`. Plain hashes, Active Model objects, and serialization libraries like [Alba](https://github.com/okuramasafumi/alba) or [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers) are supported.
-
-### Prop Transformation
-
-By default, prop keys are camelized on the way to React, so `account.plan_name` arrives as `account.planName` in your component. This makes them more idiomatic for the frontend, but you can override the `transform_props` behavior in your [configuration](#configuration).
-
 ### Layouts
 
-Action Mailer layouts are not applied to `react:` emails. React Email treats layouts like any other component, so share structure with normal React composition instead:
+Action Mailer layouts aren't applied to `react:` emails. React Email treats layouts like any other component, so share structure with normal React composition instead:
 
 ```tsx
 // app/javascript/emails/_components/email_layout.tsx
@@ -294,191 +359,11 @@ 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-or-markdown-into-a-document), add `@tiptap/html` and its server DOM, `happy-dom`:
-
-```sh
-npm i @tiptap/html happy-dom
-```
-
-To parse Markdown as well, add [`marked`](https://marked.js.org) — it converts Markdown to HTML, which then runs through the same parser:
-
-```sh
-npm i marked
-```
+### Editor
 
-Enable the `documents` option in your Vite config:
+If you're also using [@react-email/editor](https://react.email/docs/editor) to let users compose emails inside your app, `ReactEmailRails.compose` can render those stored documents on the server.
 
-```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"
-
-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]
-}
-
-export function transformDocument(document, context) {
-  const header = {
-    type: "heading",
-    attrs: { level: 1 },
-    content: [{ type: "text", text: context.brandName }],
-  }
-  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,
-  context: { brand_name: "Acme", preview_text: broadcast.subject },
-  preview: broadcast.subject,
-)
-
-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-or-markdown-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 or Markdown 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",
-  html: params[:body_html],
-  context: { brand_name: "Acme" },
-)
-
-broadcast.update!(body: document)
-```
-
-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.
-
-#### Markdown
-
-Pass `markdown:` in place of `html:` to parse Markdown — useful when the content comes from an LLM or another tool that emits Markdown more readily than HTML. It's converted to HTML with [`marked`](https://marked.js.org) and run through the same parse path, so it needs `marked` installed alongside the HTML peers (see [Setup](#setup)).
-
-```ruby
-document = ReactEmailRails.parse(
-  type: "broadcast",
-  markdown: "# Welcome\n\nThanks for signing up, **Ada**.",
-  context: { brand_name: "Acme" },
-)
-```
-
-Pass exactly one of `html:` or `markdown:` — passing both, or neither, raises `ArgumentError`.
-
-Markdown is a lower-friction *input*, not a wider one. It expresses less than HTML — headings, paragraphs, emphasis, links, lists, blockquotes, code, images, and rules — so it adds no new node types. Markdown that maps to nodes the renderer's extensions don't define (such as a GFM table without a table extension) is dropped or flattened, the same as the equivalent HTML.
-
-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 or Markdown.
-- 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.
+See [Editor rendering](docs/editor.md) for setup and usage.
 
 ## Configuration
 
@@ -497,6 +382,7 @@ If the defaults don't fit, override them in `config/initializers/react_email_rai
 | `render_timeout` | `10` seconds |
 | `render_process_max_requests` | `1_000` |
 | `on_render_error` | `nil` |
+| `deep_merge_shared_props` | `false` |
 
 #### Prop Transformation
 
@@ -516,17 +402,13 @@ ReactEmailRails.configure do |config|
 end
 ```
 
-`transform_props` only controls prop key names; props are always serialized with `as_json`.
+`transform_props` only controls prop key names. Props are always serialized with `as_json`.
 
 #### Render Modes
 
-`:subprocess` starts a fresh Node process for each render. It's simple, always uses the latest bundle, and keeps failures isolated, but pays Node startup and bundle load on every render.
-
-`:persistent` reuses one long-lived Node process per worker. It's faster because it avoids per-render startup, but uses more memory and can serve a stale component until recycled.
-
-For background email delivery, the default `:subprocess` mode is usually enough. Switch to `:persistent` when Node startup appears in traces or batch jobs render many emails from the same bundle (see [Instrumentation](#instrumentation)).
+`:subprocess` starts a fresh Node process for each render. It's simple, isolated, and always uses the latest bundle, but pays Node startup and bundle load each time.
 
-The render mode also shapes the development experience: `:subprocess` boots a fresh Vite dev server per render and always reflects your latest edits, while `:persistent` reuses the server and may serve a stale component until the process is recycled.
+`:persistent` reuses one long-lived Node process per worker. It's faster for render-heavy workers, but uses more memory and can serve a stale component until recycled. The default `:subprocess` mode is usually enough. Switch when Node startup shows up in traces or batch jobs render many emails from the same bundle.
 
 Enable persistent mode for render-heavy worker processes:
 
@@ -538,13 +420,13 @@ end
 
 Persistent mode keeps one Node child per process:
 
-- Renders are sent as newline-delimited JSON and processed one at a time, so a single child never renders concurrently. Scale throughput by adding worker processes.
-- It is fork-safe: under clustered Puma or forking job runners, each worker spawns its own child.
+- Renders are newline-delimited JSON and processed one at a time. Scale throughput with more worker processes.
+- It's fork-safe: under clustered Puma or forking job runners, each worker spawns its own child.
 - The child is recycled after `render_process_max_requests` renders to bound memory growth. Set it to `nil` to disable recycling.
 
 #### Render Options
 
-`render_options` is passed to [@react-email/render](https://react.email/docs/utilities/render). `html` options apply to HTML rendering and `text` options apply to plain-text rendering. Keys are camelized before they cross into JavaScript.
+`render_options` is passed to [@react-email/render](https://react.email/docs/utilities/render). Use `html` and `text` keys for each output. Option keys are camelized before they cross into JavaScript.
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -563,7 +445,7 @@ end
 
 #### Error Reporting
 
-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:
+Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error plus `kind:` and `component:`:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -575,7 +457,7 @@ 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 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)):
+Every render emits `render.react-email-rails` through [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html). The payload includes `kind`, `component`, and successful HTML size in `html_bytes`:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
@@ -585,9 +467,9 @@ end
 
 ### Vite Configuration
 
-Most apps only need the `reactEmailRails()` plugin from [Quick Start](#quick-start). The options below change where components are discovered, how the bundle handles dependencies, and which email-only Vite transforms run in the isolated renderer.
+Most apps only need the `reactEmailRails()` plugin from [Quick Start](#quick-start). The options below change component discovery, bundle dependency handling, and isolated renderer transforms.
 
-In development and production, the isolated renderer loads the `reactEmailRails()` plugin, JSX support, and component-facing Vite config such as `resolve`, `define`, `css`, `json`, `assetsInclude`, `esbuild`, and `oxc` — but none of your other app plugins. Forwarded config is only for compiling and resolving email components; server, preview, dependency optimization, and build output settings stay owned by React Email Rails.
+In development and production, the isolated renderer loads `reactEmailRails()`, JSX support, and component-facing Vite config such as `resolve`, `define`, `css`, `json`, `assetsInclude`, `esbuild`, and `oxc`. It doesn't load your other app plugins. Server, preview, dependency optimization, and build output settings stay owned by react-email-rails.
 
 #### Plugin Options
 
@@ -596,11 +478,7 @@ 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 |
+| `standalone` | `true` | Inline production renderer bundle dependencies |
 | `vite` | `{}` | Extra email-only Vite config for compilation and resolution |
 
 Use a custom directory:
@@ -625,7 +503,7 @@ Component names come from the Vite directory layout (see [Component Names](#comp
 
 #### Advanced: Email-Only Vite Plugins
 
-Most apps do not need extra email plugins. If email components need a transform that is not part of Vite's default pipeline, add that transform to the email renderer:
+Most apps don't need extra email plugins. If email components need a transform that isn't part of Vite's default pipeline, add that transform to the isolated renderer:
 
 ```ts
 import mdx from "@mdx-js/rollup"
@@ -643,11 +521,11 @@ export default defineConfig({
 })
 ```
 
-These `vite` options are used by `react-email-rails-dev` and `react-email-rails-build`. They are intentionally scoped to React Email. Only `assetsInclude`, `css`, `define`, `esbuild`, `json`, `oxc`, `plugins`, and `resolve` are accepted here; output settings such as `build.outDir` and `build.rollupOptions` are ignored so the Ruby renderer can always find the generated bundle.
+These `vite` options are used by `react-email-rails-dev` and `react-email-rails-build`. Only `assetsInclude`, `css`, `define`, `esbuild`, `json`, `oxc`, `plugins`, and `resolve` are accepted. Output settings such as `build.outDir` and `build.rollupOptions` are ignored so Ruby can always find the bundle.
 
 #### Standalone Builds
 
-By default the production email bundle inlines React, `@react-email/render`, and other Node dependencies. That makes the bundle larger, but it works well for Rails deploys that build assets in one stage and run without `node_modules` in the final runtime image. Development previews keep dependencies external for Vite's module runner, even when `standalone` is enabled.
+By default the production renderer bundle inlines React, `@react-email/render`, and other Node dependencies. This works well for Rails deploys that build assets in one stage and run without `node_modules` in the final image. Development previews keep dependencies external, even when `standalone` is enabled.
 
 Set `standalone: false` when your runtime already ships `node_modules` and you prefer a smaller SSR-style bundle:
 
@@ -667,7 +545,7 @@ For production deploys, run the normal Rails asset task:
 bin/rails assets:precompile
 ```
 
-The `react_email_rails:build` task is hooked into `assets:precompile` automatically. It loads your Vite config to find `reactEmailRails()` and its options, then writes `tmp/react-email-rails/emails.js` with the isolated React Email pipeline.
+The `react_email_rails:build` task is hooked into `assets:precompile` automatically. It loads `reactEmailRails()` options from your Vite config, then writes `tmp/react-email-rails/emails.js` with the email component registry. If [Editor document rendering](docs/editor.md) is enabled, the bundle also includes document renderers.
 
 You can run it directly when needed:
 
@@ -677,9 +555,9 @@ bin/rails react_email_rails:build
 
 Production rendering runs that bundle with Node. Set `SKIP_REACT_EMAIL_RAILS_BUILD=1` to skip the automatic asset hook. Directly running `bin/rails react_email_rails:build` always attempts the build.
 
-The npm package, Vite, React, and `@react-email/render` must be available when Rails runs `assets:precompile`. This is the same stage where Rails apps normally install JavaScript dependencies and build frontend assets.
+The npm package, Vite, React, and `@react-email/render` must be available when Rails runs `assets:precompile`. If you enable [Editor document rendering](docs/editor.md), its peer dependencies must be available too.
 
-The bundle is required, not an optimization. If it's missing, renders raise `ReactEmailRails::RenderError` and no mail is sent.
+The bundle is required, not an optimization. If it's missing, renders raise `ReactEmailRails::RenderError`. Action Mailer deliveries aren't sent.
 
 The Ruby gem and npm package must stay on the same version. The renderer includes a small protocol/version handshake, so mismatched installs fail with an actionable `ReactEmailRails::RenderError` instead of silently returning malformed output.
 
@@ -693,7 +571,7 @@ To confirm the renderer is ready before relying on it, run:
 bin/rails react_email_rails:verify
 ```
 
-It checks that the render command runs and that the npm package version matches the gem, then exits non-zero with an actionable message on failure. Wire it into your CI or release step to catch a missing bundle or version drift before a deploy ships — a renderer failure won't otherwise surface until the first email is sent.
+It checks that the render command runs and that the npm package version matches the gem, then exits non-zero with an actionable message on failure. Wire it into CI or release steps to catch missing bundles or version drift before the first render.
 
 For programmatic checks (for example, a health endpoint), `ReactEmailRails.healthy?` returns a boolean. If you specifically want a check at boot, call it from your own initializer and scope it to the processes that send mail so others don't pay the cost:
 

data/lib/react_email_rails/action_mailer.rb

@@ -1,6 +1,9 @@
 module ReactEmailRails::ActionMailer
   extend(ActiveSupport::Concern)
 
+  # `react_email_share` kwargs reserved for `before_action` filtering, not prop data.
+  SHARED_FILTER_OPTIONS = [:if, :unless, :only, :except].freeze
+
   prepended do
     class_attribute(:react_email_use_instance_props, default: false)
   end
@@ -9,6 +12,22 @@ module ReactEmailRails::ActionMailer
     def use_react_instance_props
       self.react_email_use_instance_props = true
     end
+
+    # Share props with every `react:` email this mailer and its subclasses render.
+    # Mirrors inertia-rails `inertia_share`; `only`/`except`/`if`/`unless` go to `before_action`.
+    def react_email_share(hash = nil, **props, &block)
+      options = props.slice(*SHARED_FILTER_OPTIONS)
+      data = hash || props.except(*SHARED_FILTER_OPTIONS)
+
+      before_action(**options) do
+        react_email_append_shared(data, block)
+      end
+    end
+  end
+
+  # Share props from within an action, e.g. conditionally before calling `mail`.
+  def react_email_share(hash = nil, **props, &block)
+    react_email_append_shared(hash || props, block)
   end
 
   def mail(headers = {}, &block)
@@ -17,8 +36,13 @@ module ReactEmailRails::ActionMailer
     headers = headers.dup
     react = headers.delete(:react)
     props = headers.delete(:props) if headers.key?(:props)
+    deep_merge = headers.delete(:deep_merge) if headers.key?(:deep_merge)
 
     component, resolved_props = ReactEmailRails::PropsResolver.new(self).resolve(react, props)
+    resolved_props = ReactEmailRails::SharedProps.new(self).merge_into(
+      resolved_props,
+      deep_merge: react_email_deep_merge?(deep_merge),
+    )
     render_options = ReactEmailRails.configuration.resolve_render_options(self)
     rendered = ReactEmailRails.render(component:, props: resolved_props, render_options:)
 
@@ -28,4 +52,18 @@ module ReactEmailRails::ActionMailer
       yield(format) if block
     end
   end
+
+  private
+
+  def react_email_append_shared(data, block)
+    store = (@_react_email_shared ||= [])
+    store << data.dup.freeze if data.present?
+    store << block if block
+  end
+
+  def react_email_deep_merge?(override)
+    return ReactEmailRails.configuration.deep_merge_shared_props if override.nil?
+
+    override
+  end
 end

data/lib/react_email_rails/configuration.rb

@@ -34,6 +34,7 @@ class ReactEmailRails::Configuration
     :render_options,
     :transform_props,
     :on_render_error,
+    :deep_merge_shared_props,
   )
 
   attr_reader(
@@ -52,6 +53,7 @@ class ReactEmailRails::Configuration
         config.render_process_max_requests = DEFAULT_RENDER_PROCESS_MAX_REQUESTS
         config.transform_props = :lower_camel
         config.on_render_error = nil
+        config.deep_merge_shared_props = false
       end
     end
   end

data/lib/react_email_rails/shared_props.rb

@@ -0,0 +1,44 @@
+# Collects props registered with `react_email_share` and merges them beneath the
+# per-mail props, which win on conflict. Mirrors inertia-rails shared data.
+class ReactEmailRails::SharedProps
+  IVAR = :@_react_email_shared
+
+  def initialize(mailer)
+    @mailer = mailer
+  end
+
+  # Returns `props` untouched when nothing is shared, so non-Hash inputs (e.g.
+  # serializers) still flow straight through to serialization.
+  def merge_into(props, deep_merge:)
+    shared = to_h
+    return props if shared.empty?
+
+    base = shared.as_json
+    incoming = props.as_json
+    deep_merge ? base.deep_merge(incoming) : base.merge(incoming)
+  end
+
+  def to_h
+    entries.each_with_object({}) do |entry, props|
+      props.merge!(resolve(entry))
+    end
+  end
+
+  private
+
+  attr_reader(:mailer)
+
+  def entries
+    mailer.instance_variable_get(IVAR) || []
+  end
+
+  # An entry is either a static Hash or a block evaluated at render time. Callable
+  # values inside a Hash are evaluated too, so `unread_count: -> { ... }` works.
+  def resolve(entry)
+    hash = entry.respond_to?(:call) ? mailer.instance_exec(&entry) : entry
+
+    (hash || {}).transform_values do |value|
+      value.respond_to?(:call) ? mailer.instance_exec(&value) : value
+    end
+  end
+end

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/react_email_rails.rb

@@ -5,6 +5,7 @@ require("active_support/concern")
 require("active_support/notifications")
 require("active_support/core_ext/object/blank")
 require("active_support/core_ext/object/json")
+require("active_support/core_ext/hash/deep_merge")
 require("active_support/inflector")
 require("rails/railtie")
 
@@ -24,6 +25,7 @@ require_relative("react_email_rails/render_modes/persistent/command_runner")
 require_relative("react_email_rails/configuration")
 require_relative("react_email_rails/tasks")
 require_relative("react_email_rails/props_resolver")
+require_relative("react_email_rails/shared_props")
 require_relative("react_email_rails/railtie")
 
 module ReactEmailRails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Supertape
@@ -164,6 +164,7 @@ files:
 - lib/react_email_rails/render_modes/subprocess/command_runner.rb
 - lib/react_email_rails/render_protocol.rb
 - lib/react_email_rails/rendered_email.rb
+- lib/react_email_rails/shared_props.rb
 - lib/react_email_rails/tasks.rb
 - lib/react_email_rails/version.rb
 - lib/tasks/react_email_rails/build.rake