react-email-rails 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05b64507c82feabb25781eaec8487c5e7282f65060abbac88719bfb2bc79d499
-  data.tar.gz: fc1f7fe4d40195537b5218818aa0fb8b72be78834238223dc377c52f7843af15
+  metadata.gz: 58d96423ee9be99d650a3ad7d164cbb8aca228ccbcc2b36d1a9be2bac2e06172
+  data.tar.gz: 370303cb64b83fd747009f59291ddf5f4598bd5670651ed89ec23edcf4b1072e
 SHA512:
-  metadata.gz: 61afe5bf3fc51e550ca9608bd91deeeb9794cd4a90bac53a7bf0fb48f2f12f5984f50dadbbd245c05e34d8dc4ab7c478f2ff8420aa94e9f57c98e39fb04bab01
-  data.tar.gz: 992fd9253d2a2cf31f9ecd37f7bd960c52efddaf74541aefa5ed124ebef4941d9404c00d7f417a6cc2d36f998d3391d8f1bf3ec3d865ec232c43c5a2df2ed4c1
+  metadata.gz: ccee408e14a4f0b831ae58d19ce6891687b273a9f017e6b97184bdbeef7a79107a4e7ba32b4e5db551c4160e2a85b62509c9c85e1ee53bca394b77857af4e2c9
+  data.tar.gz: 262e70dd3acaf9b6bd0e8d1854649bb4a475634c4b0569c69dd2498f3a8bd9093bc33e89e35fe2c6785315247838122d081e4a26206c73d8d51da97698aa31a3

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.6.0
+
+- Every `react:` email now receives `mailer` and `message` props, mirroring Action Mailer's `mailer`/`message` ERB view helpers. Rendering now happens after Action Mailer assigns headers, so `message` includes subject, addressing, and default `from`/`reply_to` values. Per-mail and shared props win on conflict, serializers whose `as_json` returns a Hash receive the context, and collection props keep their original shape. The npm package exports matching `Mailer`/`Message` TypeScript types.
+
+## 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.

data/README.md

@@ -2,15 +2,36 @@
 
 # react-email-rails
 
-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).
+Build and send Action Mailer emails with [React Email](https://react.email), TypeScript, and Vite.
+
+react-email-rails lets Rails render React Email components into HTML and plain text, then deliver them through the Action Mailer stack you already know: previews, headers, callbacks, queues, instrumentation, and delivery all keep working normally.
+
+## Why
+
+HTML email is still awkward. React Email gives you a nicer component model, email-safe primitives, Tailwind support, and TypeScript. This gem connects that workflow to Rails without replacing Action Mailer.
+
+You get:
+
+- React Email components rendered from `mail(...)`
+- HTML and plain-text output from the same component
+- Rails mailer previews, tests, queues, callbacks, and delivery
+- Vite-powered development rendering
+- A production renderer bundle built during `assets:precompile`
+- Optional persistent rendering for high-volume workers
+- Optional server-side rendering for `@react-email/editor` documents
+
+## Status
+
+react-email-rails is pre-1.0. It was extracted from [XOXO](https://xoxo.email), which is pre-launch, so the API may still change and it has not yet been battle-tested in high-volume production.
+
+The supported Ruby, Rails, Node, React, and Vite versions are tested in CI. Please [open an issue](https://github.com/heysupertape/react-email-rails/issues) for bugs, rough edges, or integration feedback.
 
 ## Contents
 
-- [Why](#why)
-- [How](#how)
-- [Status](#status)
 - [Requirements](#requirements)
-- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Your First Email](#your-first-email)
+- [How Rendering Works](#how-rendering-works)
 - [Usage](#usage)
 - [Configuration](#configuration)
 - [Deployment](#deployment)
@@ -19,73 +40,58 @@ Build and send emails using React and Rails with [React Email](https://react.ema
 - [Security](#security)
 - [License](#license)
 
-## Why
-
-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 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.
-
-## 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).
-
 ## Requirements
 
-- Ruby >= 3.3
-- Action Mailer, Active Support, and Railties >= 7.1 and < 9.0
-- Node >= 20.19
-- Vite 7 or 8
-- React 18 or 19
-- `@react-email/render` 2.x
+| Dependency | Version |
+|------------|---------|
+| Ruby | >= 3.3 |
+| Rails | Action Mailer, Active Support, and Railties >= 7.1 and < 9.0 |
+| Node | >= 20.19 |
+| Vite | 7 or 8 |
+| React | 18 or 19 |
+| `@react-email/render` | 2.x |
 
-> We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite with Rails.
+We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite in Rails apps.
 
-## Quick Start
+## Installation
 
-Add the gem:
+Add the Ruby gem:
 
 ```ruby
 # Gemfile
-
 gem "react-email-rails"
 ```
 
-### Automatic Install
-
-Run the installer:
+Then install it with Rails:
 
 ```sh
+bundle install
 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 installer 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 then follows the normal Rails lifecycle:
+After installation, the normal Rails flow applies:
 
-- `bin/rails generate react_email_rails:email ...` creates matching mailers and React components.
-- `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.
+- Generate mailers and components with `bin/rails generate react_email_rails:email ...`.
+- Run `bin/dev` in development; email components render through Vite on demand.
+- Run `bin/rails assets:precompile` for production; the renderer bundle builds automatically.
+- Run `bin/rails react_email_rails:build` directly when CI or tests need the bundle without the full asset task.
 
-### Manual Install
+### Manual Setup
 
-Install the npm package and peer dependencies manually:
+If you prefer to wire things up yourself, install the npm package and React Email dependencies:
 
 ```sh
 npm i react-email-rails @react-email/render @react-email/components react react-dom
 ```
 
-Update your Vite config to add the plugin:
+Use the equivalent command for pnpm, Yarn, or Bun if your app uses a different package manager.
+
+Then add the Vite plugin:
 
 ```ts
 // vite.config.ts
-
 import { defineConfig } from "vite"
 import { reactEmailRails } from "react-email-rails"
 
@@ -94,7 +100,7 @@ export default defineConfig({
 })
 ```
 
-### Your First Email
+## Your First Email
 
 Generate a mailer and React Email component:
 
@@ -102,13 +108,15 @@ 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 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:
+The generator follows Rails' mailer generator shape: `NAME [method method]`. It creates a mailer, React component, mailer preview, and test. It also reads `emails.path` and `emails.extension` from `reactEmailRails()` when available.
+
+Pass flags when you need to override the detected component directory or extension:
 
 ```sh
 bin/rails generate react_email_rails:email Account welcome --emails-path=app/emails --extension=jsx
 ```
 
-Edit the generated mailer to pass any necessary props:
+Update the generated mailer to pass props into the React component:
 
 ```ruby
 class AccountMailer < ApplicationMailer
@@ -128,11 +136,10 @@ class AccountMailer < ApplicationMailer
 end
 ```
 
-Edit the generated email component:
+Then edit the generated component:
 
 ```tsx
 // app/javascript/emails/account_mailer/welcome.tsx
-
 import { Body, Container, Html, Text } from "@react-email/components"
 
 type WelcomeProps = {
@@ -154,27 +161,70 @@ export default function Welcome({ account }: WelcomeProps) {
 }
 ```
 
-> [@react-email/components](https://react.email/docs/components/html) provides primitives like `<Button>`, `<Heading>`, `<Tailwind>`, and more.
+Deliver it like any other Action Mailer email:
+
+```ruby
+AccountMailer.with(account: current_account).welcome.deliver_later
+```
+
+React Email also provides primitives like [`<Button>`, `<Heading>`, `<Tailwind>`, and more](https://react.email/docs/components/html).
+
+## How Rendering Works
+
+In development, react-email-rails renders components through Vite's dev pipeline. Your email components get the same module resolution and transforms as the rest of your frontend.
+
+In production, `assets:precompile` builds a server-side renderer bundle from your Vite config. Rails runs that bundle with Node whenever an email needs to render.
 
-That's it. It now renders and delivers like any other Action Mailer email.
+Every `react:` email renders HTML and plain text from the same component. If rendering fails, the email is not sent and `ReactEmailRails::RenderError` is raised.
 
 ## Usage
 
-Pass data from your mailer. Each top-level key becomes a prop on the component's default export.
+### Passing Props
+
+Top-level keys passed to `react:` become props on the component's default export. The API is intentionally close to [inertia-rails](https://inertia-rails.dev), so apps using both libraries should feel consistent.
 
 ```ruby
-mail react: { foo: "bar" }, ...
+mail(
+  to: account.email,
+  subject: "Welcome",
+  react: {
+    account: {
+      name: account.name,
+    },
+  },
+)
 ```
 
 ```tsx
-export default function Email({ foo }: { foo: string }) {
+type WelcomeProps = {
+  account: {
+    name: string
+  }
+}
+
+export default function Welcome({ account }: WelcomeProps) {
   // ...
 }
 ```
 
-Choose the level of inference you want:
+### Component Inference
+
+By default, react-email-rails infers the component from the mailer and action:
+
+| Mailer action | Component |
+|---------------|-----------|
+| `AccountMailer#welcome` | `account_mailer/welcome` |
+| `Users::InviteMailer#new_invite` | `users/invite_mailer/new_invite` |
 
-### Implicit Component, Instance Props
+`AccountMailer#welcome` resolves to `app/javascript/emails/account_mailer/welcome.tsx` or `.jsx` with the default Vite options.
+
+Use `react: true` to render the inferred component. By default it renders with no props, which is handy for emails that take none:
+
+```ruby
+mail(to: account.email, subject: "Welcome", react: true)
+```
+
+To have `react: true` build props automatically, enable `use_react_instance_props`. The component then receives the mailer's instance variables as props:
 
 ```ruby
 class AccountMailer < ApplicationMailer
@@ -182,21 +232,24 @@ class AccountMailer < ApplicationMailer
 
   def welcome
     @account = params.fetch(:account)
-    mail react: true, to: @account.email, subject: "Welcome"
+
+    mail(to: @account.email, subject: "Welcome", react: true)
   end
 end
 ```
 
-Action Mailer's framework assigns (including `params` and `rendered_format`) are excluded from instance props.
+Action Mailer's framework assigns, including `params` and `rendered_format`, are excluded from instance props.
 
-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.
+### Explicit Components
 
-### Implicit Component, Explicit Props
+Pass a component name when the mailer action and component path do not line up:
 
 ```ruby
 mail(
-  ...
-  react: {
+  to: account.email,
+  subject: "Welcome",
+  react: "accounts/welcome",
+  props: {
     account: {
       name: account.name,
     },
@@ -204,58 +257,168 @@ mail(
 )
 ```
 
-### Explicit Component, Explicit Props
+To change naming globally, override `component_path_resolver` in your [Rails configuration](#rails-configuration).
+
+### Shared Props
+
+Use `react_email_share` to merge props into every `react:` email for a mailer and its subclasses:
+
+```ruby
+class MarketingMailer < ApplicationMailer
+  react_email_share app_name: "Acme"
+
+  react_email_share unread_count: -> { params[:account]&.unread_count }
+
+  react_email_share do
+    { brand: { name: "Acme", url: marketing_url } }
+  end
+end
+```
+
+Per-mail props win over shared props of the same name:
 
 ```ruby
 mail(
-  ...
-  react: "accounts/welcome",
-  props: {
-    account: {
-      name: account.name,
-    },
+  to: account.email,
+  subject: "Welcome",
+  react: {
+    app_name: "Acme Pro",
   },
 )
 ```
 
-These forms mirror [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
+Shared props work with `react:` hashes, `react: true`, and explicit `react: "component", props: ...` calls.
 
-### Component Names
+### Conditional Shared Props
 
-Component names are inferred from the mailer and action:
+`react_email_share` accepts the same filter options as `before_action`: `only`, `except`, `if`, and `unless`.
 
-| Mailer action | Component |
-|---------------|-----------|
-| `AccountMailer#welcome` | `account_mailer/welcome` |
-| `Users::InviteMailer#new_invite` | `users/invite_mailer/new_invite` |
+```ruby
+react_email_share only: [:welcome, :reactivation] do
+  { promotion: params.fetch(:promotion) }
+end
 
-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`.
+react_email_share if: :account_active? do
+  { account: { name: params.fetch(:account).name } }
+end
+```
+
+You can also share props inside an action before calling `mail`:
+
+```ruby
+def welcome
+  account = params.fetch(:account)
+
+  react_email_share notice: "Thanks for joining!"
+
+  mail(
+    to: account.email,
+    subject: "Welcome",
+    react: { account: account.as_json(only: [:name]) },
+  )
+end
+```
+
+### Deep Merging Shared Props
 
-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.
+Shared props are merged shallowly by default. That means a per-mail prop replaces a shared prop with the same name.
+
+Pass `deep_merge: true` to merge nested hashes instead:
+
+```ruby
+react_email_share do
+  { settings: { theme: "light", locale: "en" } }
+end
+
+mail(
+  to: account.email,
+  subject: "Welcome",
+  react: {
+    settings: {
+      theme: "dark",
+    },
+  },
+  deep_merge: true,
+)
+```
 
-Override the inferred name per mail:
+The component receives:
 
 ```ruby
-mail react: "users/welcome", props: { user: }, to:, subject:
+{ settings: { theme: "dark", locale: "en" } }
+```
+
+Set `config.deep_merge_shared_props = true` to make deep merging the default for every email.
+
+### Mailer and Message Props
+
+Every `react:` email receives `mailer` and `message` props, mirroring the [`mailer` and `message` view helpers](https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-view-helpers) available to Action Mailer ERB views.
+
+`mailer` identifies the mailer action. `message` reflects the email after Action Mailer has assigned headers and defaults, including default `from` and `reply_to` values. With the default prop transform, import the `Mailer` and `Message` types to annotate them:
+
+```tsx
+import type { Mailer, Message } from "react-email-rails"
+import { Body, Container, Html, Text } from "@react-email/components"
+
+type WelcomeProps = {
+  account: { name: string }
+  mailer: Mailer
+  message: Message
+}
+
+export default function Welcome({ account, mailer, message }: WelcomeProps) {
+  return (
+    <Html>
+      <Body>
+        <Container>
+          <Text>Welcome, {account.name}</Text>
+          <Text>Re: {message.subject}</Text>
+        </Container>
+      </Body>
+    </Html>
+  )
+}
 ```
 
-Or override `component_path_resolver` globally in your [configuration](#configuration).
+| Prop | Example |
+|------|---------|
+| `mailer.mailerName` | `"account_mailer"` |
+| `mailer.actionName` | `"welcome"` |
+| `message.subject` | `"Welcome"` |
+| `message.to` | `["account@example.com"]` |
+| `message.cc`, `message.bcc` | `["…"]` or `null` |
+| `message.from`, `message.replyTo` | `["app@example.com"]` |
+
+Context is merged before prop serialization, so keys follow `config.transform_props` just like your own props. The exported TypeScript types describe the default `:lower_camel` shape.
+
+Per-mail and shared props win on conflict, so a prop named `mailer` or `message` overrides the injected context. Serializer props receive the context when `as_json` returns a hash. Collections, arrays, and other non-object values pass through unchanged so their top-level shape is preserved.
 
 ### 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).
+Props are serialized with `as_json`, just like `render json:`. You can pass hashes, arrays, Active Model objects, and serializer output from libraries 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 `plan_name` arrives in React as `planName`. See [Prop Transformation](#prop-transformation) to change that behavior.
+
+### Component Files
 
-Prop keys are camelized by default, so `account.plan_name` arrives as `account.planName`. Override `transform_props` in your [configuration](#configuration).
+Files and directories starting with `_` are ignored as renderable email entries by default. Use them for shared components, layouts, and helpers:
+
+```text
+app/javascript/emails/
+  account_mailer/
+    welcome.tsx
+  _components/
+    email_layout.tsx
+```
+
+Ignored files can still be imported by email components.
 
 ### Layouts
 
-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:
+Action Mailer layouts are not applied to `react:` emails. In React Email, layouts are normal React components:
 
 ```tsx
 // app/javascript/emails/_components/email_layout.tsx
-
 import { Body, Container, Html } from "@react-email/components"
 import type { ReactNode } from "react"
 
@@ -276,7 +439,6 @@ export function EmailLayout({ children }: EmailLayoutProps) {
 
 ```tsx
 // app/javascript/emails/account_mailer/welcome.tsx
-
 import { Text } from "@react-email/components"
 import { EmailLayout } from "../_components/email_layout"
 
@@ -289,21 +451,28 @@ export default function Welcome() {
 }
 ```
 
-See [Component Names](#component-names) for how shared `_` files are handled.
+### Editor Documents
 
-### Editor
-
-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.
+If your app uses [@react-email/editor](https://react.email/docs/editor) to let users compose emails visually, `ReactEmailRails.compose` can render stored editor documents on the server.
 
 See [Editor rendering](docs/editor.md) for setup and usage.
 
 ## Configuration
 
-Configuration is handled primarily on the Rails side, though there are some Vite options to be aware of.
+Configuration lives in two places:
+
+- Rails configuration controls mailer behavior, prop handling, rendering mode, timeouts, and error hooks.
+- Vite configuration controls email component discovery and the renderer bundle.
 
 ### Rails Configuration
 
-If the defaults don't fit, override them in `config/initializers/react_email_rails.rb`:
+Override Rails-side defaults in `config/initializers/react_email_rails.rb`:
+
+```ruby
+ReactEmailRails.configure do |config|
+  # config.render_mode = :persistent
+end
+```
 
 | Option | Default |
 |--------|---------|
@@ -314,15 +483,16 @@ 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
+### Prop Transformation
 
-Set `transform_props` to another supported value if you prefer a different prop key style:
+Set `transform_props` to choose how Ruby prop keys are exposed to React:
 
 | Value | Example |
 |-------|---------|
 | `:camel` | `AccountName` |
-| `:lower_camel` (default) | `accountName` |
+| `:lower_camel` | `accountName` |
 | `:dash` | `account-name` |
 | `:snake` | `account_name` |
 | `:none` | preserves serialized keys |
@@ -333,15 +503,15 @@ ReactEmailRails.configure do |config|
 end
 ```
 
-`transform_props` only controls prop key names. Props are always serialized with `as_json`.
+Only prop keys are transformed. Values are always serialized with `as_json`.
 
-#### Render Modes
+### Render Modes
 
-`: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 default `:subprocess` mode starts a fresh Node process for each render. It is simple, isolated, and always uses the latest bundle, but it pays Node startup and bundle load time for each email.
 
-`: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.
+`:persistent` mode keeps one long-lived Node child process per Ruby process. It is faster for render-heavy workers, but uses more memory and can serve a stale component until the child is recycled.
 
-Enable persistent mode for render-heavy worker processes:
+Switch to persistent mode when Node startup shows up in traces or when a worker renders many emails from the same bundle:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -349,21 +519,22 @@ ReactEmailRails.configure do |config|
 end
 ```
 
-Persistent mode keeps one Node child per process:
+Persistent mode details:
 
-- 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.
+- Renders are newline-delimited JSON and processed one at a time.
+- Throughput scales with more worker processes.
+- It is fork-safe; clustered Puma and forking job runners spawn one Node child per worker.
+- The child recycles after `render_process_max_requests` renders. Set that option to `nil` to disable recycling.
 
-#### Render Options
+### Render Options
 
-`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.
+`render_options` is passed to [@react-email/render](https://react.email/docs/utilities/render). Use `html` and `text` keys to configure each output. Option keys are camelized before they cross into JavaScript.
 
 ```ruby
 ReactEmailRails.configure do |config|
   config.render_options = {
     html: {
-      pretty: Rails.env.development?
+      pretty: Rails.env.development?,
     },
     text: {
       html_to_text_options: {
@@ -374,9 +545,11 @@ ReactEmailRails.configure do |config|
 end
 ```
 
-#### Error Reporting
+`render_options` can also be a callable. When rendering from a mailer, it is evaluated in the mailer instance so it can use helpers or per-email state.
 
-Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error plus `kind:` and `component:`:
+### Error Reporting
+
+Use `on_render_error` to report failures before the exception is re-raised:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -386,33 +559,50 @@ ReactEmailRails.configure do |config|
 end
 ```
 
-#### Instrumentation
+The callback receives the error plus render context such as `kind:` and `component:`.
+
+### Instrumentation
 
-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`:
+Every render emits `render.react-email-rails` through [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html). Email payloads include `kind`, `component`, and successful HTML size in `html_bytes`.
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
-  Rails.logger.info("[react-email-rails] Rendered #{event.payload[:component]} (Duration: #{event.duration.round}ms | Size: #{event.payload[:html_bytes]} bytes)")
+  Rails.logger.info(
+    "[react-email-rails] Rendered #{event.payload[:component]} " \
+      "(#{event.duration.round}ms, #{event.payload[:html_bytes]} bytes)",
+  )
 end
 ```
 
 ### Vite Configuration
 
-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.
+Most apps only need the plugin from [Installation](#installation):
+
+```ts
+import { defineConfig } from "vite"
+import { reactEmailRails } from "react-email-rails"
+
+export default defineConfig({
+  plugins: [reactEmailRails()],
+})
+```
+
+The isolated renderer loads `reactEmailRails()`, JSX support, and component-facing Vite config such as `resolve`, `define`, `css`, `json`, `assetsInclude`, `esbuild`, and `oxc`. It does not load your other app plugins unless you explicitly add them with `vite.plugins`.
 
-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.
+Server, preview, dependency optimization, and build output settings stay owned by react-email-rails so Rails can always find the renderer bundle.
 
-#### Plugin Options
+### Vite Plugin Options
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `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` | Optional `@react-email/editor` document renderer discovery; see [Editor rendering](docs/editor.md) |
 | `standalone` | `true` | Inline production renderer bundle dependencies |
 | `vite` | `{}` | Extra email-only Vite config for compilation and resolution |
 
-Use a custom directory:
+Use a custom email directory:
 
 ```ts
 reactEmailRails({
@@ -420,7 +610,7 @@ reactEmailRails({
 })
 ```
 
-Use multiple extensions:
+Use custom extensions:
 
 ```ts
 reactEmailRails({
@@ -430,11 +620,11 @@ reactEmailRails({
 })
 ```
 
-Component names come from the Vite directory layout (see [Component Names](#component-names)). To map mailer actions to a different layout, override `component_path_resolver` on the Ruby side rather than renaming in the plugin, so both halves stay in sync.
+Component names come from the Vite directory layout. To map mailer actions to a different layout, override `component_path_resolver` on the Ruby side so both halves stay in sync.
 
-#### Advanced: Email-Only Vite Plugins
+### Email-Only Vite Plugins
 
-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:
+Most apps do not need extra email plugins. If email components need a transform that is not part of Vite's default pipeline, add it to the isolated renderer:
 
 ```ts
 import mdx from "@mdx-js/rollup"
@@ -452,13 +642,13 @@ export default defineConfig({
 })
 ```
 
-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.
+Only `assetsInclude`, `css`, `define`, `esbuild`, `json`, `oxc`, `plugins`, and `resolve` are accepted inside `vite`. Output settings such as `build.outDir` and `build.rollupOptions` are ignored.
 
-#### Standalone Builds
+### Standalone Builds
 
-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.
+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.
 
-Set `standalone: false` when your runtime already ships `node_modules` and you prefer a smaller SSR-style bundle:
+Set `standalone: false` when your runtime ships `node_modules` and you prefer a smaller SSR-style bundle:
 
 ```ts
 reactEmailRails({
@@ -466,45 +656,43 @@ reactEmailRails({
 })
 ```
 
-Externalized bundles are smaller and may build faster, but the renderer needs the externalized packages available at runtime.
+Externalized bundles can be smaller and may build faster, but the externalized packages must be available at runtime.
 
 ## Deployment
 
-For production deploys, run the normal Rails asset task:
+Production deploys should run the normal Rails asset task:
 
 ```sh
 bin/rails assets:precompile
 ```
 
-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.
+react-email-rails hooks `react_email_rails:build` into `assets:precompile`. The build task loads `reactEmailRails()` options from your Vite config and writes `tmp/react-email-rails/emails.js` with the email component registry. If [Editor rendering](docs/editor.md) is enabled, the bundle also includes document renderers.
 
-You can run it directly when needed:
+You can run the renderer build directly:
 
 ```sh
 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.
+Production rendering requires that bundle. If it is missing, rendering raises `ReactEmailRails::RenderError` and Action Mailer does not send the email.
 
-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.
+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 bundle is required, not an optimization. If it's missing, renders raise `ReactEmailRails::RenderError`. Action Mailer deliveries aren't sent.
+The npm package, Vite, React, and `@react-email/render` must be available when Rails runs `assets:precompile`. If [Editor rendering](docs/editor.md) is enabled, its peer dependencies must be available too.
 
-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.
+The Ruby gem and npm package must stay on the same version. A protocol/version handshake catches mismatched installs and raises an actionable `ReactEmailRails::RenderError`.
 
-The build command preserves `emails.path`, `emails.extension`, `emails.ignore`, `standalone`, and email-only `vite` options.
+### Verify the Renderer
 
-### Renderer Verification
-
-To confirm the renderer is ready before relying on it, run:
+Run this before relying on the production renderer:
 
 ```sh
 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 CI or release steps to catch missing bundles or version drift before the first render.
+It checks that the render command runs and that the npm package version matches the gem. It exits non-zero with an actionable message on failure, so it is safe to wire into CI or release steps.
 
-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:
+For programmatic checks, `ReactEmailRails.healthy?` returns a boolean:
 
 ```ruby
 Rails.application.config.after_initialize do
@@ -514,13 +702,31 @@ Rails.application.config.after_initialize do
 end
 ```
 
+If you check at boot, scope it to processes that send mail so the rest of the app does not pay the cost.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, checks, formatting, and release verification.
 
+The short version:
+
+```sh
+bundle install
+cd vite && pnpm install
+```
+
+Run the core checks before opening a pull request:
+
+```sh
+ruby scripts/check_version_sync.rb
+bin/test
+bin/lint
+cd vite && pnpm run build
+```
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+Bug reports and pull requests are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request so the local checks and release expectations are clear.
 
 ## Security
 
@@ -528,4 +734,4 @@ Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for deta
 
 ## License
 
-The gem and npm package are available as open source under the terms of the [MIT License](LICENSE.md).
+The Ruby gem and npm package are available as open source under the terms of the [MIT License](LICENSE.md).

data/lib/generators/react_email_rails/email_generator.rb

@@ -164,7 +164,6 @@ class ReactEmailRails::Generators::EmailGenerator < Rails::Generators::NamedBase
     )
   end
 
-  # First capture-group match across an ordered list of patterns, or nil.
   def first_capture(source, *patterns)
     patterns.each do |pattern|
       match = source[pattern, 1]

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,19 @@ module ReactEmailRails::ActionMailer
     def use_react_instance_props
       self.react_email_use_instance_props = true
     end
+
+    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
+
+  def react_email_share(hash = nil, **props, &block)
+    react_email_append_shared(hash || props, block)
   end
 
   def mail(headers = {}, &block)
@@ -17,15 +33,41 @@ 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)
-    render_options = ReactEmailRails.configuration.resolve_render_options(self)
-    rendered = ReactEmailRails.render(component:, props: resolved_props, render_options:)
+    resolved_props = ReactEmailRails::SharedProps.new(self).merge_into(
+      resolved_props,
+      deep_merge: react_email_deep_merge?(deep_merge),
+    )
 
     super(headers) do |format|
+      rendered = react_email_render(component, resolved_props)
+
       format.html { rendered.html }
       format.text { rendered.text } if rendered.text.present?
+
       yield(format) if block
     end
   end
+
+  private
+
+  def react_email_render(component, props)
+    props = ReactEmailRails::MailerContext.new(self).merge_into(props)
+    render_options = ReactEmailRails.configuration.resolve_render_options(self)
+    ReactEmailRails.render(component:, props:, render_options:)
+  end
+
+  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/mailer_context.rb

@@ -0,0 +1,40 @@
+class ReactEmailRails::MailerContext
+  MESSAGE_FIELDS = [:subject, :to, :cc, :bcc, :from, :reply_to].freeze
+
+  def initialize(mailer)
+    @mailer = mailer
+  end
+
+  def merge_into(props)
+    serialized_props = props.as_json
+    return props unless serialized_props.is_a?(Hash)
+
+    to_h.merge(serialized_props)
+  end
+
+  def to_h
+    {
+      "mailer" => mailer_context,
+      "message" => message_context,
+    }
+  end
+
+  private
+
+  attr_reader(:mailer)
+
+  def mailer_context
+    {
+      "mailer_name" => mailer.class.mailer_name,
+      "action_name" => mailer.action_name,
+    }
+  end
+
+  def message_context
+    message = mailer.message
+
+    MESSAGE_FIELDS.each_with_object({}) do |field, context|
+      context[field.to_s] = message.public_send(field)
+    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.1"
+  VERSION = "0.6.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,8 @@ 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/mailer_context")
 require_relative("react_email_rails/railtie")
 
 module ReactEmailRails
@@ -56,8 +59,7 @@ module ReactEmailRails
       perform(payload:, label: type, kind: "document", type:)
     end
 
-    # Parse semantic HTML or Markdown into an editor document Hash using the renderer's
-    # extensions. Pass exactly one of `html:` or `markdown:`.
+    # Returns an editor document Hash, built via the renderer's extensions. Pass exactly one of `html:`/`markdown:`.
     def parse(type:, html: nil, markdown: nil, context: {})
       payload = {
         kind: "parse",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Supertape
@@ -153,6 +153,7 @@ files:
 - lib/react_email_rails.rb
 - lib/react_email_rails/action_mailer.rb
 - lib/react_email_rails/configuration.rb
+- lib/react_email_rails/mailer_context.rb
 - lib/react_email_rails/props_resolver.rb
 - lib/react_email_rails/railtie.rb
 - lib/react_email_rails/render_error.rb
@@ -164,6 +165,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