react-email-rails 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d0666badbedb79a20a1fec50afc5aedde5398a3777620f5c2f6c2e080a2a5e2
-  data.tar.gz: f19f1dba07f2ad62bf5737e3fab859c33a526305963ee239a1eb63d3048cc7f9
+  metadata.gz: e2dc04e0c361e5517d66cf3a60a274b090bc5978b82ee4a77c07758ac8ca82e7
+  data.tar.gz: 027c7e6c6e4510621b6738c271f273a1a89a248e6de59772bc0af6fec7eebe4d
 SHA512:
-  metadata.gz: 3905f2042d9932512be861bd7bf0be13f7dde1e9f481dae3ebbbe36f676f8562ecc29532a91649e1e64102454427057599d10baa47866ed9bbab6699163546a8
-  data.tar.gz: 6236d1b78f000473a2bb696bbf204ce72143bd62abdc1008a0ce0fa05be88777ca2416101107894f92feaea79d16fbc7f9fc4e13d4c00e8b52ca31dff289fa64
+  metadata.gz: b044fc510c92a914031d4932586b12f2a16c306fee35f4cb4088f22093910456b3a8e3fe4a1909d1e8a67ba10a6235462f4531858a6f575e3516ef8bea20e260
+  data.tar.gz: d30686390cf1c1d435a24ec640d3a5873cf7137e211c67e6e316a660c3ffa67ae6c78787b90075676ddab90ded4282b2db6730195120ff954c919fd58a3610f3

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.12.0
+
+- **Breaking:** Remove `config.render_mode`. There is one renderer: a long-lived Node child per Ruby process, speaking newline-delimited JSON. Delete `config.render_mode = :persistent` from initializers. Set `config.render_process_max_requests = 1` to recycle the child after every email.
+- **Breaking:** Replace `config.transform_props` (`:camel`, `:lower_camel`, `:dash`, `:snake`, `:none`) with `config.prop_transformer`, matching [inertia-rails](https://inertia-rails.dev/guide/configuration#prop_transformer). The default is a no-op (`->(props:) { props }`), so keys stay as `as_json` produced them. Camelize in an initializer if you want the previous 0.11 behavior. The exported `Mailer` and `Message` TypeScript types now describe that default snake_case shape.
+- Render HTML once and derive plain text with `toPlainText`, so `htmlToTextOptions` and `data-skip-in-text` apply to the same markup.
+- Raise clearer errors when a component is missing (including a capped list of known names) or has no default export.
+- Default `render_timeout` to 30 seconds in development so the first Vite-backed render can finish booting.
+- Timeouts with no stdout mention matching gem and npm versions, so a gem 0.12 talking to an older package that waits for EOF is easier to diagnose.
+- Recycle the Node child after invalid JSON so the next render can succeed.
+- Include Node stderr when the child exits without a protocol line, instead of reporting only that it exited.
+- Treat only `{ "health": true }` as a health check so a render payload that also sets `health` still renders.
+- Apply `html.pretty` only to the HTML body so pretty-printing does not change plain text.
+
+## 0.11.1
+
+- Republish of 0.11.0 with no code changes. The 0.11.0 npm package was never published: npm provenance publishing requires GitHub-hosted runners, so the release workflow's publish job now runs on one. Do not use gem 0.11.0; it has no matching npm package.
+
+## 0.11.0
+
+- Generated applications now use React Email 6's unified `react-email` package for email components instead of `@react-email/components`.
+- `@react-email/render` is now a runtime dependency of the `react-email-rails` npm package instead of a peer dependency, so applications no longer install it directly. The npm package now declares `react-dom` as a peer dependency alongside `react`, matching what the renderer already required at runtime.
+
 ## 0.10.0
 
 - **Breaking:** Remove the instance-level `react_share` helper (calling `react_share` from within an action before `mail`). Pass per-mail props directly in the `react:` hash instead; use the class-level `react_share` (with `only`/`except`/`if`/`unless`) for conditional sharing.

data/README.md

@@ -8,16 +8,7 @@ react-email-rails lets Rails render React Email components into HTML and plain t
 
 ## 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
+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: components render through Vite in development and a prebuilt renderer bundle in production, using a long-lived Node process per Ruby process.
 
 ## Status
 
@@ -34,7 +25,6 @@ The supported Ruby, Rails, Node, React, and Vite versions are tested in CI. Plea
 - [Usage](#usage)
 - [Configuration](#configuration)
 - [Deployment](#deployment)
-- [Development](#development)
 - [Contributing](#contributing)
 - [Security](#security)
 - [License](#license)
@@ -43,12 +33,12 @@ The supported Ruby, Rails, Node, React, and Vite versions are tested in CI. Plea
 
 | Dependency | Version |
 |------------|---------|
-| Ruby | >= 3.3 |
-| Rails | Action Mailer, Active Support, and Railties >= 7.1 and < 9.0 |
-| Node | >= 20.19 |
+| Ruby | 3.3+ |
+| Rails | 7.1–8.x |
+| Node | 20.19+ |
 | Vite | 7 or 8 |
 | React | 18 or 19 |
-| `@react-email/render` | 2.x |
+| React Email | 6.x |
 
 We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite in Rails apps.
 
@@ -68,21 +58,20 @@ bundle install
 bin/rails generate react_email_rails:install
 ```
 
-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 installer creates `config/initializers/react_email_rails.rb`, installs missing JavaScript dependencies when it can detect your package manager, adds `reactEmailRails()` to `vite.config.*` (creating `vite.config.ts` if none exists), and creates `app/javascript/emails`.
 
 After installation, the normal Rails flow applies:
 
 - 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 Setup
 
 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
+npm i react-email-rails react-email react react-dom
 ```
 
 Use the equivalent command for pnpm, Yarn, or Bun if your app uses a different package manager.
@@ -107,7 +96,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 a mailer, React component, mailer preview, and test. It also reads `emails.path` and `emails.extension` from `reactEmailRails()` when available.
+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 your `reactEmailRails()` Vite options when available.
 
 Pass flags when you need to override the detected component directory or extension:
 
@@ -139,7 +128,7 @@ Then edit the generated component:
 
 ```tsx
 // app/javascript/emails/account_mailer/welcome.tsx
-import { Body, Container, Html, Text } from "@react-email/components"
+import { Body, Container, Html, Text } from "react-email"
 
 type WelcomeProps = {
   account: {
@@ -166,21 +155,21 @@ Deliver it like any other Action Mailer email:
 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).
+React Email also provides primitives like [`<Button>`, `<Heading>`, `<Tailwind>`, and more](https://react.email/components).
 
 ## Rendering
 
-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 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. A long-lived Node child stays warm across previews and `deliver_now` calls so Vite is not cold-started for every email.
 
-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.
+In production, `assets:precompile` builds a server-side renderer bundle from your Vite config. Rails keeps one Node child per Ruby process and renders through that bundle.
 
-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.
+Every `react:` email renders HTML once and derives plain text from that markup. If rendering fails, the email is not sent and `ReactEmailRails::RenderError` is raised.
 
 ### Live-Reloading Previews
 
-In development, Action Mailer previews automatically reload themselves when you edit an email component. react-email-rails registers a [preview interceptor](https://api.rubyonrails.org/classes/ActionMailer/Base.html#class-ActionMailer::Base-label-Previewing+emails) that injects `@vite/client` into the preview, and the `reactEmailRails()` plugin broadcasts a full reload over Vite's websocket whenever a file under your emails directory changes.
+In development, Action Mailer previews automatically reload themselves when you edit an email component. react-email-rails registers a [preview interceptor](https://api.rubyonrails.org/classes/ActionMailer/Base.html#class-ActionMailer::Base-label-Previewing+emails) that injects `@vite/client` into the preview, and the `reactEmailRails()` plugin broadcasts a full reload over Vite's WebSocket whenever a file under your emails directory changes.
 
-The `live_reload_url` defaults to Vite's `http://localhost:5173`, but you can point elsewhere if needed, or set it to a falsy value to disable live reload. (See [Configuration](#configuration))
+`live_reload_url` defaults to Vite's `http://localhost:5173`. Point it elsewhere if your dev server runs on a different port, or set it to a falsy value to disable live reload:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -192,31 +181,7 @@ end
 
 ### 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(
-  to: account.email,
-  subject: "Welcome",
-  react: {
-    account: {
-      name: account.name,
-    },
-  },
-)
-```
-
-```tsx
-type WelcomeProps = {
-  account: {
-    name: string
-  }
-}
-
-export default function Welcome({ account }: WelcomeProps) {
-  // ...
-}
-```
+Top-level keys passed to `react:` become props on the component's default export, as shown in the [Quick Start](#quick-start). The API is intentionally close to [inertia-rails](https://inertia-rails.dev), so apps using both libraries should feel consistent.
 
 ### Component Inference
 
@@ -249,7 +214,7 @@ class AccountMailer < ApplicationMailer
 end
 ```
 
-Action Mailer's framework assigns, including `params` and `rendered_format`, are excluded from instance props.
+Action Mailer's internal assigns, such as `params` and `rendered_format`, are excluded from instance props.
 
 To make React the default for every action, set `default react: true` on the mailer (or `ApplicationMailer`). Each `mail` call then renders the inferred component without repeating `react: true`, and a single action can opt back out with `react: false`:
 
@@ -357,54 +322,40 @@ Set `config.deep_merge_shared_props = true` to make deep merging the default for
 
 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:
+`mailer` identifies the mailer action. `message` reflects the email after Action Mailer has assigned headers and defaults, including default `from` and `reply_to` values. 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>
-  )
-}
 ```
 
 | Prop | Example |
 |------|---------|
-| `mailer.mailerName` | `"account_mailer"` |
-| `mailer.actionName` | `"welcome"` |
+| `mailer.mailer_name` | `"account_mailer"` |
+| `mailer.action_name` | `"welcome"` |
 | `message.subject` | `"Welcome"` |
 | `message.to` | `["account@example.com"]` |
 | `message.cc`, `message.bcc` | `["…"]` or `null` |
-| `message.from`, `message.replyTo` | `["app@example.com"]` |
+| `message.from`, `message.reply_to` | `["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.
+Context is merged before prop serialization, so keys follow `config.prop_transformer` just like your own props. The exported TypeScript types describe the default (untransformed) 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.
+Per-mail and shared props win on conflict, so a prop named `mailer` or `message` overrides the injected context. When props come from a serializer, the context is merged in as long as `as_json` returns a hash; collections, arrays, and other non-object values pass through unchanged so their top-level shape is preserved.
 
 ### Prop Serialization
 
 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 keys are camelized by default, so `plan_name` arrives in React as `planName`. See [Prop Transformation](#prop-transformation) to change that behavior.
+Keys are left as serialized by default, so `plan_name` arrives in React as `plan_name`. See [Prop Transformation](#prop-transformation) to camelize them.
 
 ### Component Files
 
-Files and directories starting with `_` are ignored as renderable email entries by default. Use them for shared components, layouts, and helpers:
+Files and directories starting with `_` are excluded from the email component registry by default. Use them for shared components, layouts, and helpers:
 
 ```text
 app/javascript/emails/
@@ -422,7 +373,7 @@ Action Mailer layouts are not applied to `react:` emails. In React Email, layout
 
 ```tsx
 // app/javascript/emails/_components/email_layout.tsx
-import { Body, Container, Html } from "@react-email/components"
+import { Body, Container, Html } from "react-email"
 import type { ReactNode } from "react"
 
 type EmailLayoutProps = {
@@ -442,7 +393,7 @@ export function EmailLayout({ children }: EmailLayoutProps) {
 
 ```tsx
 // app/javascript/emails/account_mailer/welcome.tsx
-import { Text } from "@react-email/components"
+import { Text } from "react-email"
 import { EmailLayout } from "../_components/email_layout"
 
 export default function Welcome() {
@@ -458,7 +409,7 @@ export default function Welcome() {
 
 Configuration lives in two places:
 
-- Rails configuration controls mailer behavior, prop handling, rendering mode, timeouts, and error hooks.
+- Rails configuration controls mailer behavior, prop handling, timeouts, and error hooks.
 - Vite configuration controls email component discovery and the renderer bundle.
 
 ### Rails Configuration
@@ -467,17 +418,16 @@ Override Rails-side defaults in `config/initializers/react_email_rails.rb`:
 
 ```ruby
 ReactEmailRails.configure do |config|
-  # config.render_mode = :persistent
+  # config.render_timeout = 10
 end
 ```
 
 | Option | Default |
 |--------|---------|
 | `component_path_resolver` | `->(mailer:, action:) { "#{mailer}/#{action}" }` |
-| `transform_props` | `:lower_camel` |
-| `render_mode` | `:subprocess` |
+| `prop_transformer` | `->(props:) { props }` |
 | `render_options` | `{}` |
-| `render_timeout` | `10` seconds |
+| `render_timeout` | `30` seconds in development, `10` seconds otherwise |
 | `render_process_max_requests` | `1_000` |
 | `on_render_error` | `nil` |
 | `deep_merge_shared_props` | `false` |
@@ -485,48 +435,35 @@ end
 
 ### Prop Transformation
 
-Set `transform_props` to choose how Ruby prop keys are exposed to React:
+Use `prop_transformer` to change props after `as_json` and before they reach React. The default is a no-op, matching [inertia-rails](https://inertia-rails.dev/guide/configuration#prop_transformer).
 
-| Value | Example |
-|-------|---------|
-| `:camel` | `AccountName` |
-| `:lower_camel` | `accountName` |
-| `:dash` | `account-name` |
-| `:snake` | `account_name` |
-| `:none` | preserves serialized keys |
+To work with `snake_case` in Ruby and `camelCase` in components:
 
 ```ruby
 ReactEmailRails.configure do |config|
-  config.transform_props = :none
+  config.prop_transformer = lambda do |props:|
+    props.deep_transform_keys { |key| key.to_s.camelize(:lower) }
+  end
 end
 ```
 
-Only prop keys are transformed. Values are always serialized with `as_json`.
-
-### Render Modes
+The transformer receives one hash at a time: the root props object, or each object in a top-level collection. Nested hashes inside a single object are left to the transformer — `deep_transform_keys` walks those.
 
-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.
+### Render Process
 
-`: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.
+Each Ruby process keeps one long-lived Node child. Renders are newline-delimited JSON and processed one at a time. Throughput scales with more worker processes. The child is fork-safe: clustered Puma and forking job runners spawn one Node child per worker.
 
-Switch to persistent mode when Node startup shows up in traces or when a worker renders many emails from the same bundle:
+The child recycles after `render_process_max_requests` renders so a leaked or stale renderer cannot live forever. Set that option to `nil` to disable recycling, or to `1` to start a fresh Node process for every email:
 
 ```ruby
 ReactEmailRails.configure do |config|
-  config.render_mode = :persistent
+  config.render_process_max_requests = 1
 end
 ```
 
-Persistent mode details:
-
-- 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` 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.
+`render_options` is passed to [@react-email/render](https://react.email/docs/utilities/render). HTML is rendered once; plain text is derived from that markup with `toPlainText` (or `unstableToPlainText` when `unstable_text_conversion` is set). `html.pretty` is applied only to the HTML part, so it does not change the text body. `text.html_to_text_options` is forwarded to `toPlainText`. Option keys are camelized before they cross into JavaScript, so `html_to_text_options` becomes `htmlToTextOptions`.
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -561,7 +498,7 @@ The callback receives the error plus render context such as `component:`.
 
 ### Instrumentation
 
-Every render emits `render.react-email-rails` through [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html). Payloads include `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). Payloads include the `component` and, on success, the rendered HTML size in `html_bytes`.
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
@@ -574,18 +511,9 @@ end
 
 ### Vite Configuration
 
-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()],
-})
-```
+Most apps only need the bare `reactEmailRails()` plugin from [Installation](#installation).
 
-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`.
+The isolated renderer loads `reactEmailRails()`, JSX support, and component-facing Vite config such as `assetsInclude`, `css`, `define`, `esbuild`, `json`, `oxc`, and `resolve`. It does not load your other app plugins unless you explicitly add them with `vite.plugins`.
 
 Server, preview, dependency optimization, and build output settings stay owned by react-email-rails so Rails can always find the renderer bundle.
 
@@ -617,7 +545,7 @@ reactEmailRails({
 })
 ```
 
-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.
+Component names come from the file layout under `emails.path`. To map mailer actions to a different layout, override `component_path_resolver` on the Ruby side so both halves stay in sync.
 
 ### Email-Only Vite Plugins
 
@@ -653,7 +581,7 @@ reactEmailRails({
 })
 ```
 
-Externalized bundles can be smaller and may build faster, but the externalized packages must be available at runtime.
+Externalized bundles can be smaller and may build faster, but the packages they reference must be available at runtime.
 
 ## Deployment
 
@@ -663,7 +591,7 @@ Production deploys should run the normal Rails asset task:
 bin/rails assets:precompile
 ```
 
-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.
+react-email-rails hooks `react_email_rails:build` into `assets:precompile` (and `react_email_rails:clobber` into `assets:clobber`). The build task loads `reactEmailRails()` options from your Vite config and writes `tmp/react-email-rails/emails.js` with the email component registry.
 
 You can run the renderer build directly:
 
@@ -673,9 +601,9 @@ bin/rails react_email_rails:build
 
 Production rendering requires that bundle. If it is missing, rendering raises `ReactEmailRails::RenderError` and Action Mailer does not send the email.
 
-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.
+Set `SKIP_REACT_EMAIL_RAILS_BUILD=1` to skip the automatic asset hooks. 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`.
+The npm package, Vite, and React must be available when Rails runs `assets:precompile`.
 
 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`.
 
@@ -701,29 +629,9 @@ 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. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request so the local checks and release expectations are clear.
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the checks to run before opening a pull request, and release expectations.
 
 ## Security
 

data/lib/generators/react_email_rails/install_generator.rb

@@ -7,8 +7,7 @@ module ReactEmailRails::Generators; end
 class ReactEmailRails::Generators::InstallGenerator < Rails::Generators::Base
   JAVASCRIPT_PACKAGES = [
     "react-email-rails",
-    "@react-email/render",
-    "@react-email/components",
+    "react-email",
     "react",
     "react-dom",
   ].freeze

data/lib/generators/react_email_rails/templates/email/component.tsx

@@ -1,4 +1,4 @@
-import { Body, Container, Heading, Html, Text } from "@react-email/components"
+import { Body, Container, Heading, Html, Text } from "react-email"
 
 export default function <%= @component_name %>() {
   return (

data/lib/react_email_rails/configuration.rb

@@ -5,21 +5,11 @@ class ReactEmailRails::Configuration
   DEV_RENDER_BIN = "node_modules/.bin/react-email-rails-dev"
 
   DEFAULT_RENDER_TIMEOUT = 10
+  DEVELOPMENT_RENDER_TIMEOUT = 30
   DEFAULT_RENDER_PROCESS_MAX_REQUESTS = 1_000
   DEFAULT_LIVE_RELOAD_URL = "http://localhost:5173"
 
-  RENDER_MODES = {
-    subprocess: ReactEmailRails::RenderModes::Subprocess,
-    persistent: ReactEmailRails::RenderModes::Persistent,
-  }.freeze
-
-  KEY_TRANSFORMS = {
-    camel: ->(key) { key.to_s.camelize },
-    lower_camel: ->(key) { key.to_s.camelize(:lower) },
-    dash: ->(key) { key.to_s.underscore.dasherize },
-    snake: ->(key) { key.to_s.underscore },
-    none: ->(key) { key },
-  }.freeze
+  DEFAULT_PROP_TRANSFORMER = ->(props:) { props }
 
   DEFAULT_RENDER_COMMAND = lambda do
     if Rails.env.development?
@@ -32,14 +22,13 @@ class ReactEmailRails::Configuration
   attr_accessor(
     :component_path_resolver,
     :render_options,
-    :transform_props,
     :on_render_error,
     :deep_merge_shared_props,
     :live_reload_url,
   )
 
   attr_reader(
-    :render_mode,
+    :prop_transformer,
     :render_timeout,
     :render_process_max_requests,
   )
@@ -48,11 +37,10 @@ class ReactEmailRails::Configuration
     def default
       new.tap do |config|
         config.component_path_resolver = ->(mailer:, action:) { "#{mailer}/#{action}" }
-        config.render_mode = :subprocess
         config.render_options = {}
-        config.render_timeout = DEFAULT_RENDER_TIMEOUT
+        config.render_timeout = Rails.env.development? ? DEVELOPMENT_RENDER_TIMEOUT : DEFAULT_RENDER_TIMEOUT
         config.render_process_max_requests = DEFAULT_RENDER_PROCESS_MAX_REQUESTS
-        config.transform_props = :lower_camel
+        config.prop_transformer = DEFAULT_PROP_TRANSFORMER
         config.on_render_error = nil
         config.deep_merge_shared_props = false
         config.live_reload_url = DEFAULT_LIVE_RELOAD_URL
@@ -66,12 +54,12 @@ class ReactEmailRails::Configuration
     live_reload_url.to_s.chomp("/")
   end
 
-  def render_mode=(value)
-    if (value.is_a?(Symbol) || value.is_a?(String)) && !RENDER_MODES.key?(value.to_sym)
-      raise(ArgumentError, "Unknown react-email-rails render mode: #{value.inspect}")
+  def prop_transformer=(value)
+    unless value.respond_to?(:call)
+      raise(ArgumentError, "react-email-rails prop_transformer must be callable")
     end
 
-    @render_mode = value
+    @prop_transformer = value
   end
 
   def render_timeout=(value)
@@ -88,14 +76,6 @@ class ReactEmailRails::Configuration
     @render_process_max_requests = value
   end
 
-  def resolved_render_mode
-    return render_mode unless render_mode.is_a?(Symbol) || render_mode.is_a?(String)
-
-    RENDER_MODES.fetch(render_mode.to_sym) do
-      raise(ArgumentError, "Unknown react-email-rails render mode: #{render_mode.inspect}")
-    end
-  end
-
   def resolve_render_options(context = nil)
     value =
       if render_options.respond_to?(:call) && context
@@ -106,7 +86,7 @@ class ReactEmailRails::Configuration
         render_options
       end
 
-    deep_transform_keys(value.as_json, KEY_TRANSFORMS.fetch(:lower_camel))
+    camelize_render_option_keys(value.as_json)
   end
 
   private
@@ -116,23 +96,26 @@ class ReactEmailRails::Configuration
   end
 
   def serialize_props(props)
-    deep_transform_keys(props.as_json, key_transform)
+    transform_serialized_props(props.as_json)
   end
 
-  def key_transform
-    transform = transform_props.respond_to?(:to_sym) ? transform_props.to_sym : transform_props
-
-    KEY_TRANSFORMS.fetch(transform) do
-      raise(ArgumentError, "Unknown react-email-rails prop transform: #{transform_props.inspect}")
+  def transform_serialized_props(value)
+    case value
+    when Hash
+      prop_transformer.call(props: value)
+    when Array
+      value.map { |item| transform_serialized_props(item) }
+    else
+      value
     end
   end
 
-  def deep_transform_keys(value, transform)
+  def camelize_render_option_keys(value)
     case value
-    when Array
-      value.map { |item| deep_transform_keys(item, transform) }
     when Hash
-      value.transform_keys { |key| transform.call(key) }.transform_values { |item| deep_transform_keys(item, transform) }
+      value.deep_transform_keys { |key| key.to_s.camelize(:lower) }
+    when Array
+      value.map { |item| camelize_render_option_keys(item) }
     else
       value
     end

data/lib/react_email_rails/mailer_context.rb

@@ -33,8 +33,8 @@ class ReactEmailRails::MailerContext
   def message_context
     message = mailer.message
 
-    MESSAGE_FIELDS.each_with_object({}) do |field, context|
-      context[field.to_s] = message.public_send(field)
+    MESSAGE_FIELDS.to_h do |field|
+      [field.to_s, message.public_send(field)]
     end
   end
 end

data/lib/react_email_rails/render_protocol.rb

@@ -6,10 +6,6 @@ module ReactEmailRails
   module RenderProtocol
     extend(self)
 
-    def healthy_result?(result)
-      result.status.success? && compatible_response?(JSON.parse(result.stdout))
-    end
-
     def compatible_response?(body)
       body["ok"] == true && compatible_metadata?(body)
     end

data/lib/react_email_rails/{render_modes/persistent/server.rb → renderer/child.rb}

@@ -1,10 +1,6 @@
-class ReactEmailRails::RenderModes::Persistent::Server
+class ReactEmailRails::Renderer::Child
   STDERR_LIMIT = 8 * 1024
 
-  Status = Data.define(:success) do
-    def success? = success
-  end
-
   def initialize(command)
     @command = command
     @mutex = Mutex.new
@@ -14,17 +10,35 @@ class ReactEmailRails::RenderModes::Persistent::Server
     @requests = 0
   end
 
-  def capture(input:, timeout:, max_requests:)
+  def exchange(input, timeout:, max_requests:)
     with_retry_on_broken_pipe do
-      capture_once(input:, timeout:).tap { recycle_if_needed(max_requests) }
+      request(input, timeout:).tap { recycle_if_needed(max_requests) }
     end
   end
 
   def health_check(timeout:)
-    with_retry_on_broken_pipe { health_check_once(timeout:) }
+    with_retry_on_broken_pipe { request(JSON.generate(health: true), timeout:) }
   end
 
   def stop
+    if @mutex.owned?
+      stop_unlocked
+    else
+      @mutex.synchronize { stop_unlocked }
+    end
+  end
+
+  def abandon
+    release_io
+  rescue IOError
+    nil
+  end
+
+  private
+
+  attr_reader(:command)
+
+  def stop_unlocked
     if @wait_thread&.alive?
       terminate_process("TERM", @wait_thread.pid)
       @wait_thread.join(1)
@@ -37,14 +51,6 @@ class ReactEmailRails::RenderModes::Persistent::Server
     release_io
   end
 
-  def abandon
-    release_io
-  rescue IOError
-    nil
-  end
-
-  private
-
   def release_io
     [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
     @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
@@ -58,38 +64,13 @@ class ReactEmailRails::RenderModes::Persistent::Server
     begin
       @mutex.synchronize(&block)
     rescue Errno::EPIPE, IOError
-      failure("render process exited before responding")
+      failed("render process exited before responding")
     end
   end
 
-  attr_reader(:command)
-
-  def capture_once(input:, timeout:)
-    response = request(input, timeout:)
-    return failure(response["error"].to_s.presence || "render process failed") unless response["ok"]
-
-    success(JSON.generate(
-      {
-        protocolVersion: response["protocolVersion"],
-        packageVersion: response["packageVersion"],
-      }.tap do |body|
-        body[:html] = response["html"] if response.key?("html")
-        body[:text] = response["text"] if response.key?("text")
-      end,
-    ))
-  rescue JSON::ParserError => e
-    failure("render process returned invalid JSON: #{e.message}")
-  end
-
-  def health_check_once(timeout:)
-    response = request(JSON.generate(health: true), timeout:)
-    response["ok"] ? success(JSON.generate(response)) : failure(response["error"].to_s.presence || "render process failed")
-  rescue JSON::ParserError => e
-    failure("render process returned invalid JSON: #{e.message}")
-  end
-
   def start
-    @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*command, "--persistent", pgroup: true)
+    release_io
+    @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*command, pgroup: true)
     @stderr_buffer = +""
     @stdout_buffer = +""
     @requests = 0
@@ -108,9 +89,12 @@ class ReactEmailRails::RenderModes::Persistent::Server
     @stdin.flush
 
     line = read_response_line(timeout)
-    return { "ok" => false, "error" => "render process exited before responding" } unless line
+    return failed("render process exited before responding") unless line
 
     JSON.parse(line)
+  rescue JSON::ParserError => e
+    stop
+    failed("render process returned invalid JSON: #{e.message}")
   end
 
   def read_response_line(timeout)
@@ -128,7 +112,10 @@ class ReactEmailRails::RenderModes::Persistent::Server
 
       remaining = deadline - monotonic_time
       if remaining <= 0 || IO.select([@stdout], nil, nil, remaining).nil?
+        silent = line.empty? && @stdout_buffer.empty?
         stop
+        raise(Timeout::Error, unmatched_package_message) if silent
+
         raise(Timeout::Error)
       end
 
@@ -139,9 +126,14 @@ class ReactEmailRails::RenderModes::Persistent::Server
       end
     end
   rescue EOFError
+    wait_for_stderr
     line.presence
   end
 
+  def unmatched_package_message
+    "no response received; gem and npm package react-email-rails must both be #{ReactEmailRails::VERSION}"
+  end
+
   def consume_buffered_response_line
     separator = @stdout_buffer.index("\n")
     return unless separator
@@ -160,7 +152,8 @@ class ReactEmailRails::RenderModes::Persistent::Server
   end
 
   def drain_stderr
-    @stderr.each do |chunk|
+    loop do
+      chunk = @stderr.readpartial(4096)
       @stderr_mutex.synchronize do
         @stderr_buffer << chunk
         @stderr_buffer = @stderr_buffer.byteslice(-STDERR_LIMIT, STDERR_LIMIT) if @stderr_buffer.bytesize > STDERR_LIMIT
@@ -170,20 +163,17 @@ class ReactEmailRails::RenderModes::Persistent::Server
     nil
   end
 
-  def success(stdout)
-    ReactEmailRails::RenderModes::Subprocess::CommandRunner::Result.new(
-      stdout:,
-      stderr: "",
-      status: Status.new(true),
-    )
+  def wait_for_stderr
+    @stderr_reader&.join(1)
   end
 
-  def failure(message)
-    ReactEmailRails::RenderModes::Subprocess::CommandRunner::Result.new(
-      stdout: "",
-      stderr: [message, stderr_buffer].reject(&:blank?).join("\n"),
-      status: Status.new(false),
-    )
+  def failed(message)
+    wait_for_stderr unless @wait_thread&.alive?
+
+    {
+      "ok" => false,
+      "error" => [message, stderr_buffer].reject(&:blank?).join("\n"),
+    }
   end
 
   def stderr_buffer

data/lib/react_email_rails/{render_modes/subprocess.rb → renderer.rb}

@@ -1,50 +1,86 @@
-class ReactEmailRails::RenderModes::Subprocess
+class ReactEmailRails::Renderer
   class << self
     def healthy?(command:, timeout:)
-      result = CommandRunner.capture([*command, "--health"], timeout:)
-      ReactEmailRails::RenderProtocol.healthy_result?(result)
+      body = child_for(command).health_check(timeout:)
+      ReactEmailRails::RenderProtocol.compatible_response?(body)
     rescue StandardError
       false
     end
+
+    def stop_all
+      @mutex.synchronize do
+        @children&.each_value(&:stop)
+        @children&.clear
+      end
+    end
+
+    private
+
+    def exchange(command, input, timeout:, max_requests:)
+      child_for(command).exchange(input, timeout:, max_requests:)
+    end
+
+    def child_for(command)
+      @mutex.synchronize do
+        reset_after_fork
+        @children[command.map(&:to_s)] ||= Child.new(command)
+      end
+    end
+
+    def reset_after_fork
+      return if @owner_pid == Process.pid && @children
+
+      @children&.each_value(&:abandon)
+      @children = {}
+      @owner_pid = Process.pid
+    end
   end
 
+  @mutex = Mutex.new
+
   def initialize(payload:, label:)
     @payload = payload
     @label = label
   end
 
   def render
-    run
-  end
+    body = exchange
+    raise(render_error(error_message(body["error"]))) unless body["ok"]
 
-  private
-
-  attr_reader(:payload, :label)
-
-  def run
-    result = capture(payload_json)
-    raise(render_error(error_message(result.stderr, result.status))) unless result.status.success?
-
-    body = JSON.parse(result.stdout)
     validate_metadata!(body)
     build_rendered_email(body)
-  rescue JSON::ParserError => e
-    raise(render_error("render process returned invalid JSON: #{e.message}"))
   rescue KeyError => e
     raise(render_error("render process returned an invalid response: missing #{e.key.inspect}"))
   end
 
-  def capture(input)
+  private
+
+  attr_reader(:payload, :label)
+
+  def exchange
     with_capture_rescues do
       validate_command!
-      CommandRunner.capture(command, input:, timeout: render_timeout)
+      self.class.send(
+        :exchange,
+        command,
+        payload_json,
+        timeout: render_timeout,
+        max_requests: render_process_max_requests,
+      )
     end
   end
 
   def with_capture_rescues
     yield
-  rescue Timeout::Error
-    raise(render_error("render process timed out after #{render_timeout}s"))
+  rescue Timeout::Error => e
+    detail = e.message
+    suffix =
+      if detail.present? && detail != "Timeout::Error" && detail != "execution expired"
+        " (#{detail})"
+      else
+        ""
+      end
+    raise(render_error("render process timed out after #{render_timeout}s#{suffix}"))
   rescue Errno::ENOENT
     raise(render_error("render command not found: #{command.inspect}"))
   end
@@ -57,12 +93,16 @@ class ReactEmailRails::RenderModes::Subprocess
     ReactEmailRails.configuration.render_timeout
   end
 
+  def render_process_max_requests
+    ReactEmailRails.configuration.render_process_max_requests
+  end
+
   def payload_json
     @payload_json ||= JSON.generate(payload)
   end
 
-  def error_message(stderr, status)
-    stderr.to_s.strip.presence || "render process exited with #{status}"
+  def error_message(message)
+    message.to_s.strip.presence || "render process failed"
   end
 
   def validate_command!
@@ -97,3 +137,5 @@ class ReactEmailRails::RenderModes::Subprocess
     ReactEmailRails::RenderError.new("React Email render failed for #{label}: #{message}")
   end
 end
+
+at_exit { ReactEmailRails::Renderer.stop_all }

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.10.0"
+  VERSION = "0.12.0"
 end

data/lib/react_email_rails.rb

@@ -6,6 +6,7 @@ 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/core_ext/hash/keys")
 require("active_support/inflector")
 require("rails/railtie")
 
@@ -16,12 +17,8 @@ require_relative("react_email_rails/render_protocol")
 require_relative("react_email_rails/action_mailer")
 require_relative("react_email_rails/render_error")
 require_relative("react_email_rails/rendered_email")
-require_relative("react_email_rails/render_modes")
-require_relative("react_email_rails/render_modes/subprocess")
-require_relative("react_email_rails/render_modes/subprocess/command_runner")
-require_relative("react_email_rails/render_modes/persistent")
-require_relative("react_email_rails/render_modes/persistent/server")
-require_relative("react_email_rails/render_modes/persistent/command_runner")
+require_relative("react_email_rails/renderer")
+require_relative("react_email_rails/renderer/child")
 require_relative("react_email_rails/configuration")
 require_relative("react_email_rails/tasks")
 require_relative("react_email_rails/props_resolver")
@@ -45,7 +42,7 @@ module ReactEmailRails
       payload[:renderOptions] = render_options if render_options.present?
 
       instrument(component:) do
-        configuration.resolved_render_mode.new(payload:, label: component).render
+        renderer_class.new(payload:, label: component).render
       end
     rescue ReactEmailRails::RenderError => e
       configuration.on_render_error&.call(e, component:)
@@ -53,7 +50,7 @@ module ReactEmailRails
     end
 
     def healthy?
-      configuration.resolved_render_mode.healthy?(
+      Renderer.healthy?(
         command: configuration.send(:resolved_render_command),
         timeout: configuration.render_timeout,
       )
@@ -63,6 +60,10 @@ module ReactEmailRails
 
     private
 
+    def renderer_class
+      Renderer
+    end
+
     def serialized_props(value)
       configuration.send(:serialize_props, value)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Supertape
@@ -158,14 +158,10 @@ files:
 - lib/react_email_rails/props_resolver.rb
 - lib/react_email_rails/railtie.rb
 - lib/react_email_rails/render_error.rb
-- lib/react_email_rails/render_modes.rb
-- lib/react_email_rails/render_modes/persistent.rb
-- lib/react_email_rails/render_modes/persistent/command_runner.rb
-- lib/react_email_rails/render_modes/persistent/server.rb
-- lib/react_email_rails/render_modes/subprocess.rb
-- 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/renderer.rb
+- lib/react_email_rails/renderer/child.rb
 - lib/react_email_rails/shared_props.rb
 - lib/react_email_rails/tasks.rb
 - lib/react_email_rails/version.rb

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

@@ -1,40 +0,0 @@
-class ReactEmailRails::RenderModes::Persistent::CommandRunner
-  @mutex = Mutex.new
-
-  class << self
-    def capture(command, input:, timeout:, max_requests: nil)
-      server_for(command).capture(input:, timeout:, max_requests:)
-    end
-
-    def healthy?(command, timeout:)
-      result = server_for(command).health_check(timeout:)
-      ReactEmailRails::RenderProtocol.healthy_result?(result)
-    rescue StandardError
-      false
-    end
-
-    def stop_all
-      @mutex.synchronize do
-        @servers&.each_value(&:stop)
-        @servers&.clear
-      end
-    end
-
-    private
-
-    def server_for(command)
-      @mutex.synchronize do
-        reset_after_fork
-        @servers[command.map(&:to_s)] ||= ReactEmailRails::RenderModes::Persistent::Server.new(command)
-      end
-    end
-
-    def reset_after_fork
-      return if @owner_pid == Process.pid && @servers
-
-      @servers&.each_value(&:abandon)
-      @servers = {}
-      @owner_pid = Process.pid
-    end
-  end
-end

data/lib/react_email_rails/render_modes/persistent.rb

@@ -1,26 +0,0 @@
-class ReactEmailRails::RenderModes::Persistent < ReactEmailRails::RenderModes::Subprocess
-  class << self
-    def healthy?(command:, timeout:)
-      CommandRunner.healthy?(command, timeout:)
-    end
-  end
-
-  private
-
-  def capture(input)
-    with_capture_rescues do
-      CommandRunner.capture(
-        command,
-        input:,
-        timeout: render_timeout,
-        max_requests: render_process_max_requests,
-      )
-    end
-  end
-
-  def render_process_max_requests
-    ReactEmailRails.configuration.render_process_max_requests
-  end
-end
-
-at_exit { ReactEmailRails::RenderModes::Persistent::CommandRunner.stop_all }

data/lib/react_email_rails/render_modes/subprocess/command_runner.rb

@@ -1,56 +0,0 @@
-class ReactEmailRails::RenderModes::Subprocess::CommandRunner
-  Result = Data.define(:stdout, :stderr, :status)
-
-  class << self
-    def capture(command, input: nil, timeout:)
-      new(command:, input:, timeout:).capture
-    end
-  end
-
-  def initialize(command:, input:, timeout:)
-    @command = command
-    @input = input
-    @timeout = timeout
-  end
-
-  def capture
-    Open3.popen3(*command, pgroup: true) do |stdin, stdout, stderr, wait_thread|
-      out_reader = read_async(stdout)
-      err_reader = read_async(stderr)
-
-      write_input(stdin)
-
-      if wait_thread.join(timeout).nil?
-        terminate_process("KILL", wait_thread.pid)
-        wait_thread.join
-        out_reader.kill
-        err_reader.kill
-        raise(Timeout::Error)
-      end
-
-      Result.new(stdout: out_reader.value, stderr: err_reader.value, status: wait_thread.value)
-    end
-  end
-
-  private
-
-  attr_reader(:command, :input, :timeout)
-
-  def read_async(io)
-    Thread.new { io.read }.tap { |thread| thread.report_on_exception = false }
-  end
-
-  def write_input(stdin)
-    stdin.write(input) if input
-  rescue Errno::EPIPE
-    nil
-  ensure
-    stdin.close
-  end
-
-  def terminate_process(signal, pid)
-    Process.kill(signal, -pid)
-  rescue Errno::ESRCH, Errno::EPERM
-    nil
-  end
-end

data/lib/react_email_rails/render_modes.rb

@@ -1 +0,0 @@
-module ReactEmailRails::RenderModes; end