react-email-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5aaa4184f5aef5765da5cefbb47b85c6b1619f61d8cf3d7f722c6268fe8bfdf
+  data.tar.gz: 25d7d5100887b3976a0c258aa83df20c74080e042bea88f16767c4d7dc227055
+SHA512:
+  metadata.gz: 78c3a0fb601dd5d81d2705872d3d2b7de0ed7876dd02013fc9b9108f0adbabd36e39b1f9dd92128d2a9005ee514679e7fcc3b8b5983ef21374c7d5a57c913349
+  data.tar.gz: 7a3a777b82c24144e8447c086004f61cb3c1f9d6dff596c6a309c1d103a6751eef8b78f45445794a028c9e15aea56a2930df11d933cc551d6d95f4cfda4f566e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public release.

data/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Bug reports and pull requests are welcome.
+
+## Development
+
+Install dependencies:
+
+```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
+```
+
+The Ruby gem version in `lib/react_email_rails/version.rb` is the package version source of truth. The renderer protocol version in `lib/react_email_rails/render_protocol.rb` is also synced into the Vite package. Run `cd vite && pnpm run sync:version` after changing either one.
+
+## Release Checks
+
+Before publishing, verify both packages can be built:
+
+```sh
+bundle exec rake build
+cd vite && pnpm pack --dry-run
+```
+
+## Publishing
+
+Releases are tag-driven. Pushing `vX.Y.Z` to GitHub runs `.github/workflows/release.yml`, publishes the Ruby gem to RubyGems, publishes the Vite package to npm, and creates the GitHub Release with the built `.gem` and `.tgz` artifacts.
+
+### Patch, Minor, and Major Releases
+
+Prepare the version bump:
+
+```sh
+ruby scripts/prepare_release.rb patch
+# or: ruby scripts/prepare_release.rb minor
+# or: ruby scripts/prepare_release.rb major
+```
+
+Replace the generated `CHANGELOG.md` TODO entry with the actual release notes, then run the checks:
+
+```sh
+ruby scripts/check_version_sync.rb
+bin/test
+bin/lint
+cd vite && pnpm run ci && pnpm pack --dry-run
+```
+
+Commit the release prep on `main` or open and merge a release pull request. Then tag the release commit:
+
+```sh
+git switch main
+git pull --ff-only origin main
+VERSION=$(ruby -r ./lib/react_email_rails/version -e 'print ReactEmailRails::VERSION')
+ruby scripts/check_release_tag.rb "v$VERSION"
+git tag -a "v$VERSION" -m "v$VERSION"
+git push origin "v$VERSION"
+```
+
+The GitHub release workflow handles the rest. If publishing fails before both registries are updated, do not reuse the same version unless neither registry accepted it; bump to the next patch version and release again.

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Supertape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,492 @@
+# React Email + Rails
+
+Build and send emails using React and Rails — a seamless integration between [React Email](https://react.email) and [Action Mailer](https://guides.rubyonrails.org/action_mailer_basics.html).
+
+## Contents
+
+- [Why](#why)
+- [How](#how)
+- [Status](#status)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Deployment](#deployment)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Security](#security)
+- [License](#license)
+
+## Why
+
+Building HTML emails is painfully archaic. [React Email](https://react.email) is a collection of unstyled components for building emails with React, Tailwind, and TypeScript. This gem brings that power directly into your Rails app: write emails as React components and send them through Action Mailer.
+
+## 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,** Vite builds a server-side email bundle ahead of time. The plugin adds a dedicated `email` build environment, so your normal `vite build` emits the bundle alongside your client assets.
+
+Delivery, headers, multipart parts, 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
+
+> We recommend [rails_vite](https://github.com/skryukov/rails_vite/) for Vite with Rails.
+
+## Quick Start
+
+Add the gem:
+
+```ruby
+# Gemfile
+
+gem "react-email-rails"
+```
+
+### Automatic Install
+
+Run the installer:
+
+```sh
+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`.
+
+### Manual Install
+
+Install the npm package and peer dependencies manually:
+
+```sh
+npm i react-email-rails @react-email/render @react-email/components react react-dom
+```
+
+Update your Vite config to add the plugin:
+
+```ts
+// vite.config.ts
+
+import { defineConfig } from "vite"
+import { reactEmailRails } from "react-email-rails"
+
+export default defineConfig({
+  plugins: [reactEmailRails()],
+})
+```
+
+### Your First Email
+
+Generate a mailer and React Email component:
+
+```sh
+bin/rails generate react_email_rails:email Account welcome
+```
+
+The generator follows Rails' mailer generator shape: `NAME [method method]`. It creates `app/mailers/account_mailer.rb`, matching components under your configured React Email directory, plus a mailer preview and test.
+
+The generator reads `emails.path` and `emails.extension` from `reactEmailRails()` when available. Pass flags to override them:
+
+```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:
+
+```ruby
+class AccountMailer < ApplicationMailer
+  def welcome
+    account = params.fetch(:account)
+
+    mail(
+      to: account.email,
+      subject: "Welcome",
+      react: {
+        account: {
+          name: account.name,
+        },
+      },
+    )
+  end
+end
+```
+
+Edit the generated email component:
+
+```tsx
+// app/javascript/emails/account_mailer/welcome.tsx
+
+import { Body, Container, Html, Text } from "@react-email/components"
+
+type WelcomeProps = {
+  account: {
+    name: string
+  }
+}
+
+export default function Welcome({ account }: WelcomeProps) {
+  return (
+    <Html>
+      <Body>
+        <Container>
+          <Text>Welcome, {account.name}</Text>
+        </Container>
+      </Body>
+    </Html>
+  )
+}
+```
+
+> [@react-email/components](https://react.email/docs/components/html) provides primitives like `<Button>`, `<Heading>`, `<Tailwind>`, and more.
+
+That's it — it now renders and delivers like any other Action Mailer email.
+
+## Usage
+
+Pass data from your mailers and each top-level key becomes a prop on the React component's default export.
+
+```ruby
+mail react: { foo: "bar" }, ...
+```
+
+```tsx
+export default function Email({ foo }: { foo: string }) {
+  // ...
+}
+```
+
+Choose the level of inference you want:
+
+### Implicit Component, Instance Props
+
+```ruby
+class AccountMailer < ApplicationMailer
+  use_react_instance_props
+
+  def welcome
+    @account = params.fetch(:account)
+    mail react: true, to: @account.email, subject: "Welcome"
+  end
+end
+```
+
+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.
+
+### Implicit Component, Explicit Props
+
+```ruby
+mail(
+  ...
+  react: {
+    account: {
+      name: account.name,
+    },
+  },
+)
+```
+
+### Explicit Component, Explicit Props
+
+```ruby
+mail(
+  ...
+  react: "accounts/welcome",
+  props: {
+    account: {
+      name: account.name,
+    },
+  },
+)
+```
+
+These forms mirror [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
+
+### Component Names
+
+Component names are inferred from the mailer and action:
+
+| Mailer action | Component |
+|---------------|-----------|
+| `AccountMailer#welcome` | `account_mailer/welcome` |
+| `Users::InviteMailer#new_invite` | `users/invite_mailer/new_invite` |
+
+Rails derives `account_mailer` from `AccountMailer` via its `mailer_name`. The default Vite plugin resolves those names under `app/javascript/emails`, so `account_mailer/welcome` maps to `app/javascript/emails/account_mailer/welcome.tsx` or `.jsx`.
+
+Files and directories starting with `_` are ignored as renderable email entries by default. Use them for shared components such as `_components/email_layout.tsx`; they can still be imported by email components.
+
+Override the inferred name per mail:
+
+```ruby
+mail react: "users/welcome", props: { user: }, to:, subject:
+```
+
+Or override `component_path_resolver` globally in your [configuration](#configuration).
+
+### Prop Serialization
+
+Just like `render json:` in controllers, you can pass any object that responds to `as_json` to `mail react:`. Plain hashes, Active Model objects, and serialization libraries like [Alba](https://github.com/okuramasafumi/alba) or [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers) are supported.
+
+### Prop Transformation
+
+By default, prop keys are camelized on the way to React, so `account.plan_name` arrives as `account.planName` in your component. This makes them more idiomatic for the frontend, but you can override the `transform_props` behavior in your [configuration](#configuration).
+
+### Layouts
+
+Action Mailer layouts are not applied to `react:` emails. React Email treats layouts like any other component, so share structure with normal React composition instead:
+
+```tsx
+// app/javascript/emails/_components/email_layout.tsx
+
+import { Body, Container, Html } from "@react-email/components"
+import type { ReactNode } from "react"
+
+type EmailLayoutProps = {
+  children: ReactNode
+}
+
+export function EmailLayout({ children }: EmailLayoutProps) {
+  return (
+    <Html>
+      <Body>
+        <Container>{children}</Container>
+      </Body>
+    </Html>
+  )
+}
+```
+
+```tsx
+// app/javascript/emails/account_mailer/welcome.tsx
+
+import { Text } from "@react-email/components"
+import { EmailLayout } from "../_components/email_layout"
+
+export default function Welcome() {
+  return (
+    <EmailLayout>
+      <Text>Welcome</Text>
+    </EmailLayout>
+  )
+}
+```
+
+See [Component Names](#component-names) for how shared `_` files are handled.
+
+## Configuration
+
+Configuration is handled primarily on the Rails side, though there are some Vite options to be aware of.
+
+### Rails Configuration
+
+If the defaults don't fit, override them in `config/initializers/react_email_rails.rb`:
+
+| Option | Default |
+|--------|---------|
+| `component_path_resolver` | `->(mailer:, action:) { "#{mailer}/#{action}" }` |
+| `transform_props` | `:lower_camel` |
+| `render_mode` | `:subprocess` |
+| `render_options` | `{}` |
+| `render_timeout` | `10` seconds |
+| `render_process_max_requests` | `1_000` |
+| `on_render_error` | `nil` |
+| `verify_render_on_boot` | `false` |
+
+#### Prop Transformation
+
+Set `transform_props` to another supported value if you prefer a different prop key style:
+
+| Value | Example |
+|-------|---------|
+| `:camel` | `AccountName` |
+| `:lower_camel` (default) | `accountName` |
+| `:dash` | `account-name` |
+| `:snake` | `account_name` |
+| `:none` | preserves serialized keys |
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.transform_props = :none
+end
+```
+
+`transform_props` only controls prop key names; props are always serialized with `as_json`.
+
+#### Render Modes
+
+`:subprocess` starts a fresh Node process for each render. It's simple, always uses the latest bundle, and keeps failures isolated, but pays Node startup and bundle load on every render.
+
+`:persistent` reuses one long-lived Node process per worker. It's faster because it avoids per-render startup, but uses more memory and can serve a stale component until recycled.
+
+For background email delivery, the default `:subprocess` mode is usually enough. Switch to `:persistent` when Node startup appears in traces or batch jobs render many emails from the same bundle (see [Instrumentation](#instrumentation)).
+
+The render mode also shapes the development experience: `:subprocess` boots a fresh Vite dev server per render and always reflects your latest edits, while `:persistent` reuses the server and may serve a stale component until the process is recycled.
+
+Enable persistent mode for render-heavy worker processes:
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.render_mode = :persistent
+end
+```
+
+Persistent mode keeps one Node child per process:
+
+- Renders are sent as newline-delimited JSON and processed one at a time, so a single child never renders concurrently. Scale throughput by adding worker processes.
+- It is fork-safe: under clustered Puma or forking job runners, each worker spawns its own child.
+- The child is recycled after `render_process_max_requests` renders to bound memory growth. Set it to `nil` to disable recycling.
+
+#### Render Options
+
+`render_options` is passed to [@react-email/render](https://react.email/docs/utilities/render). `html` options apply to HTML rendering and `text` options apply to plain-text rendering. Keys are camelized before they cross into JavaScript.
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.render_options = {
+    html: {
+      pretty: Rails.env.development?
+    },
+    text: {
+      html_to_text_options: {
+        selectors: [{ selector: "img", format: "skip" }],
+      },
+    },
+  }
+end
+```
+
+#### Error Reporting
+
+Use `on_render_error` to report failures before the exception is re-raised:
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.on_render_error = ->(error, component:) {
+    Rails.error.report(error, context: { component: })
+  }
+end
+```
+
+#### Instrumentation
+
+Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries the `component` name and, on success, the rendered HTML size in `html_bytes`:
+
+```ruby
+ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
+  Rails.logger.info(
+    "[react-email-rails] rendered #{event.payload[:component]} " \
+    "(#{event.payload[:html_bytes]} bytes) in #{event.duration.round(1)}ms"
+  )
+end
+```
+
+### Vite Configuration
+
+Most apps only need the `reactEmailRails()` plugin from [Quick Start](#quick-start). The options below change where components are discovered and how the bundle handles dependencies.
+
+In development, the renderer loads the `reactEmailRails()` plugin, JSX support, and your `resolve`, `define`, and `css` config — but none of your other dev-server plugins.
+
+#### 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` |
+| `standalone` | `true` | Inline SSR dependencies with `ssr.noExternal: true` |
+
+Use a custom directory:
+
+```ts
+reactEmailRails({
+  emails: "app/emails",
+})
+```
+
+Use multiple extensions:
+
+```ts
+reactEmailRails({
+  emails: {
+    extension: [".email.tsx", ".email.jsx"],
+  },
+})
+```
+
+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.
+
+#### Standalone Builds
+
+By default the email bundle inlines React, `@react-email/render`, and other Node dependencies. That makes the bundle larger, but it works well for Rails deploys that build assets in one stage and run without `node_modules` in the final runtime image.
+
+Set `standalone: false` when your runtime already ships `node_modules` and you prefer a smaller SSR-style bundle:
+
+```ts
+reactEmailRails({
+  standalone: false,
+})
+```
+
+Externalized bundles are smaller and may build faster, but the renderer needs the externalized packages available at runtime.
+
+## Deployment
+
+For a standard Rails + Vite deploy, there is nothing extra to configure. Keep running your normal asset build and the email bundle is emitted alongside your client assets.
+
+### Standard Vite Builds
+
+The plugin registers a dedicated `email` [build environment](https://vite.dev/guide/api-environment), so a normal `vite build` writes `tmp/react-email-rails/emails.js`, which the bundled production renderer runs with Node. With [rails_vite](https://github.com/skryukov/rails_vite/), this already happens during `assets:precompile`.
+
+The bundle is required, not an optimization. If it's missing, renders raise `ReactEmailRails::RenderError` and no mail is sent. Make sure `vite build` runs anywhere that renders mail, the same as for the rest of your assets.
+
+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.
+
+### Custom Vite Builds
+
+To emit the bundle without a dedicated command, the plugin opts your project into Vite's [whole-app build](https://vite.dev/guide/api-environment):
+
+- A plain `vite build` builds every configured environment in one pass. For a standard client-only app, that's just your client assets plus the `email` bundle.
+- If you've defined other Vite environments, such as a custom `ssr` build, they build in the same pass too.
+- If your Vite config defines a custom `builder.buildApp`, make sure it builds `builder.environments.email` alongside your other environments. Custom builders replace Vite's default whole-app build orchestration.
+
+### Runtime Dependencies
+
+For runtime dependency tradeoffs, see [Standalone Builds](#standalone-builds).
+
+### Boot Verification
+
+Boot verification is disabled by default. If you want the app to check the renderer during boot, scope it to the same processes that build or ship the bundle:
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.verify_render_on_boot = -> { Rails.env.production? && Sidekiq.server? }
+  config.render_mode = :persistent if Rails.env.production? && Sidekiq.server?
+end
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, checks, formatting, and release verification.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for details.
+
+## License
+
+The gem and npm package are available as open source under the terms of the [MIT License](LICENSE.md).

data/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Please report security issues privately by emailing hi@supertape.com.
+
+Do not open a public GitHub issue for suspected vulnerabilities. Include the affected version, a minimal reproduction when possible, and any relevant deployment details.

data/lib/generators/react_email_rails/USAGE

@@ -0,0 +1,19 @@
+Description:
+    Install React Email Rails into a Rails + Vite application.
+
+Example:
+    bin/rails generate react_email_rails:install
+
+    This creates config/initializers/react_email_rails.rb, installs missing
+    JavaScript dependencies when a package manager can be detected, adds
+    reactEmailRails() to vite.config.*, and creates app/javascript/emails.
+
+Options:
+    --package-manager=npm|pnpm|yarn|bun
+        Choose the JavaScript package manager used to install dependencies.
+
+    --skip-package-install
+        Do not install JavaScript dependencies.
+
+    --skip-vite
+        Do not create or update vite.config.*.