react-email-rails 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58d96423ee9be99d650a3ad7d164cbb8aca228ccbcc2b36d1a9be2bac2e06172
-  data.tar.gz: 370303cb64b83fd747009f59291ddf5f4598bd5670651ed89ec23edcf4b1072e
+  metadata.gz: 957e5d57adf900478fa7736755f400bd424dbfc4aa47bee2e6ef82822fa9d048
+  data.tar.gz: 7bdd67d8de3ce6051c1849338337e74734fb51514d18eee0931ba172c2edac93
 SHA512:
-  metadata.gz: ccee408e14a4f0b831ae58d19ce6891687b273a9f017e6b97184bdbeef7a79107a4e7ba32b4e5db551c4160e2a85b62509c9c85e1ee53bca394b77857af4e2c9
-  data.tar.gz: 262e70dd3acaf9b6bd0e8d1854649bb4a475634c4b0569c69dd2498f3a8bd9093bc33e89e35fe2c6785315247838122d081e4a26206c73d8d51da97698aa31a3
+  metadata.gz: 7e44fad8be9e76043f9811a5cadffc9ffe4a6da0dd4b649b283a6f5af599d600d4c69750a2dc454224923abab985204f07238978def3fd2ca3af7506c73444d6
+  data.tar.gz: 86617b862cfaf09b4a20a21918b042732648d8a8383dcf319cbe4ba77e5f982d9dd98d0abdc643d8ef902dfcc46485f0428547c0aed2a2eccae7e508a87ee5c2

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.7.0
+
+- Add development live-reloading for Action Mailer previews. A development-only preview interceptor injects Vite's `@vite/client` into previews, and the `reactEmailRails()` plugin triggers a full reload when an email component changes, so the open preview refreshes on save. Configure the dev-server URL with `live_reload_url`, or set it to a falsy value to disable.
+
+## 0.6.1
+
+- Fix `react:` rendering — and the `mailer`/`message` props — being skipped for actions that opt in through a class-level `default react: true` rather than a per-`mail` `react:` option. `mail` now resolves `react` (in any form: `true`, a component string, or a prop hash) from the mailer's `default`, a per-action `react: false` opts back out, and the internal `react`/`props`/`deep_merge` options never leak onto the message as email headers.
+
 ## 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.

data/README.md

@@ -30,8 +30,8 @@ The supported Ruby, Rails, Node, React, and Vite versions are tested in CI. Plea
 
 - [Requirements](#requirements)
 - [Installation](#installation)
-- [Your First Email](#your-first-email)
-- [How Rendering Works](#how-rendering-works)
+- [Quick Start](#quick-start)
+- [Rendering](#rendering)
 - [Usage](#usage)
 - [Configuration](#configuration)
 - [Deployment](#deployment)
@@ -100,7 +100,7 @@ export default defineConfig({
 })
 ```
 
-## Your First Email
+## Quick Start
 
 Generate a mailer and React Email component:
 
@@ -169,7 +169,7 @@ 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
+## 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.
 
@@ -177,6 +177,18 @@ In production, `assets:precompile` builds a server-side renderer bundle from you
 
 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.
 
+### 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.
+
+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))
+
+```ruby
+ReactEmailRails.configure do |config|
+  config.live_reload_url = "http://localhost:3036" # or nil or false to disable
+end
+```
+
 ## Usage
 
 ### Passing Props
@@ -240,6 +252,14 @@ end
 
 Action Mailer's framework assigns, including `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`:
+
+```ruby
+class ApplicationMailer < ActionMailer::Base
+  default react: true
+end
+```
+
 ### Explicit Components
 
 Pass a component name when the mailer action and component path do not line up:
@@ -484,6 +504,7 @@ end
 | `render_process_max_requests` | `1_000` |
 | `on_render_error` | `nil` |
 | `deep_merge_shared_props` | `false` |
+| `live_reload_url` | `http://localhost:5173` |
 
 ### Prop Transformation
 

data/lib/generators/react_email_rails/email_generator.rb

@@ -139,7 +139,6 @@ class ReactEmailRails::Generators::EmailGenerator < Rails::Generators::NamedBase
     ].find { |path| File.exist?(File.join(destination_root, path)) }
   end
 
-  # The reactEmailRails({ ... }) plugin call, up to the option key being scanned for.
   PLUGIN_OPENING = /reactEmailRails\s*\(\s*\{.*?/m
 
   def emails_path_from_vite_config

data/lib/generators/react_email_rails/vite_config_files.rb

@@ -2,7 +2,6 @@ module ReactEmailRails; end
 module ReactEmailRails::Generators; end
 
 module ReactEmailRails::Generators
-  # Candidate Vite config filenames in precedence order; shared by both generators.
   VITE_CONFIG_FILES = [
     "vite.config.ts",
     "vite.config.mts",

data/lib/react_email_rails/action_mailer.rb

@@ -1,7 +1,6 @@
 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
@@ -28,12 +27,15 @@ module ReactEmailRails::ActionMailer
   end
 
   def mail(headers = {}, &block)
-    return super unless headers.is_a?(Hash) && headers.key?(:react)
+    return super unless headers.is_a?(Hash)
+    return super if headers.empty? && @_mail_was_called
 
-    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)
+    react = headers.key?(:react) ? headers[:react] : compute_default(self.class.default[:react])
+    return super unless react
+
+    props = headers[:props]
+    deep_merge = headers[:deep_merge]
+    headers = headers.except(:react, :props, :deep_merge)
 
     component, resolved_props = ReactEmailRails::PropsResolver.new(self).resolve(react, props)
     resolved_props = ReactEmailRails::SharedProps.new(self).merge_into(
@@ -53,6 +55,10 @@ module ReactEmailRails::ActionMailer
 
   private
 
+  def assign_headers_to_message(message, headers)
+    super(message, headers.except(:react, :props, :deep_merge))
+  end
+
   def react_email_render(component, props)
     props = ReactEmailRails::MailerContext.new(self).merge_into(props)
     render_options = ReactEmailRails.configuration.resolve_render_options(self)

data/lib/react_email_rails/configuration.rb

@@ -1,5 +1,4 @@
 class ReactEmailRails::Configuration
-  # Must match OUT_DIR/BUNDLE_FILE in vite/src/index.ts (check_version_sync.rb asserts it).
   BUNDLE_PATH = "tmp/react-email-rails/emails.js"
   BUILD_BIN = "node_modules/.bin/react-email-rails-build"
   CONFIG_BIN = "node_modules/.bin/react-email-rails-config"
@@ -7,6 +6,7 @@ class ReactEmailRails::Configuration
 
   DEFAULT_RENDER_TIMEOUT = 10
   DEFAULT_RENDER_PROCESS_MAX_REQUESTS = 1_000
+  DEFAULT_LIVE_RELOAD_URL = "http://localhost:5173"
 
   RENDER_MODES = {
     subprocess: ReactEmailRails::RenderModes::Subprocess,
@@ -35,6 +35,7 @@ class ReactEmailRails::Configuration
     :transform_props,
     :on_render_error,
     :deep_merge_shared_props,
+    :live_reload_url,
   )
 
   attr_reader(
@@ -54,10 +55,17 @@ class ReactEmailRails::Configuration
         config.transform_props = :lower_camel
         config.on_render_error = nil
         config.deep_merge_shared_props = false
+        config.live_reload_url = DEFAULT_LIVE_RELOAD_URL
       end
     end
   end
 
+  def resolve_live_reload_url
+    return if live_reload_url.blank?
+
+    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}")
@@ -88,8 +96,6 @@ class ReactEmailRails::Configuration
     end
   end
 
-  # A callable render_options is instance_exec'd against `context` (the mailer) when given,
-  # so it can use per-mail helpers; otherwise it's called or returned as-is.
   def resolve_render_options(context = nil)
     value =
       if render_options.respond_to?(:call) && context

data/lib/react_email_rails/preview_live_reload.rb

@@ -0,0 +1,33 @@
+class ReactEmailRails::PreviewLiveReload
+  SCRIPT_TEMPLATE = %(<script type="module" src="%s/@vite/client"></script>)
+  BODY_CLOSE = %r{</body>}i
+
+  class << self
+    def previewing_email(message)
+      url = ReactEmailRails.configuration.resolve_live_reload_url
+      return unless url
+
+      part = html_part(message)
+      return unless part
+
+      part.body = inject(part.body.decoded, url)
+    end
+
+    private
+
+    def html_part(message)
+      return message.html_part if message.html_part
+      return message if message.mime_type == "text/html"
+
+      nil
+    end
+
+    def inject(html, url)
+      snippet = format(SCRIPT_TEMPLATE, url)
+      return html if html.include?(snippet)
+      return "#{html}#{snippet}" unless BODY_CLOSE.match?(html)
+
+      html.sub(BODY_CLOSE) { |tag| "#{snippet}#{tag}" }
+    end
+  end
+end

data/lib/react_email_rails/props_resolver.rb

@@ -1,6 +1,5 @@
 class ReactEmailRails::PropsResolver
   INTERNAL_ASSIGN_PREFIX = "_"
-  # Some Action Mailer framework assigns do not use the internal `_` prefix.
   RESERVED_ASSIGNS = ["params", "rendered_format"].freeze
 
   def initialize(mailer)
@@ -34,7 +33,6 @@ class ReactEmailRails::PropsResolver
   end
 
   def assign_props
-    # `react: true` infers the component; instance vars become props only when the mailer opts in.
     return {} unless mailer.class.react_email_use_instance_props
 
     mailer.instance_variables.each_with_object({}) do |ivar, props|

data/lib/react_email_rails/railtie.rb

@@ -2,6 +2,7 @@ class ReactEmailRails::Railtie < Rails::Railtie
   initializer("react-email-rails.action_mailer") do
     ActiveSupport.on_load(:action_mailer) do
       prepend(ReactEmailRails::ActionMailer)
+      register_preview_interceptor(ReactEmailRails::PreviewLiveReload) if Rails.env.development?
     end
   end
 

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

@@ -1,5 +1,4 @@
 class ReactEmailRails::RenderModes::Persistent::CommandRunner
-  # Eager (not lazy) so concurrent first renders can't each create separate Mutexes.
   @mutex = Mutex.new
 
   class << self
@@ -30,8 +29,6 @@ class ReactEmailRails::RenderModes::Persistent::CommandRunner
       end
     end
 
-    # A forked child inherits the parent's Servers and their open pipes; sharing those pipes
-    # interleaves requests across processes, so drop them without killing the parent's process.
     def reset_after_fork
       return if @owner_pid == Process.pid && @servers
 

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

@@ -1,7 +1,6 @@
 class ReactEmailRails::RenderModes::Persistent::Server
   STDERR_LIMIT = 8 * 1024
 
-  # Minimal Process::Status stand-in; only #success? is ever read.
   Status = Data.define(:success) do
     def success? = success
   end
@@ -38,7 +37,6 @@ class ReactEmailRails::RenderModes::Persistent::Server
     release_io
   end
 
-  # Release this process's copy of an inherited child's pipes without signalling the parent-owned process.
   def abandon
     release_io
   rescue IOError
@@ -47,14 +45,12 @@ class ReactEmailRails::RenderModes::Persistent::Server
 
   private
 
-  # Shared by stop (which also kills the process) and abandon (which must not).
   def release_io
     [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
     @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
     @stdout_buffer.clear
   end
 
-  # Run under the mutex; on a broken pipe, stop and retry once (the child respawns).
   def with_retry_on_broken_pipe(&block)
     @mutex.synchronize(&block)
   rescue Errno::EPIPE, IOError
@@ -72,8 +68,6 @@ class ReactEmailRails::RenderModes::Persistent::Server
     response = request(input, timeout:)
     return failure(response["error"].to_s.presence || "render process failed") unless response["ok"]
 
-    # Re-serialize into the same Result.stdout contract the subprocess produces, so
-    # Subprocess#run parses and validates every render uniformly.
     success(JSON.generate(
       {
         protocolVersion: response["protocolVersion"],

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -8,8 +8,6 @@ class ReactEmailRails::RenderModes::Subprocess
     end
   end
 
-  # `label` names the render in error messages. `response` reads the reply as `:email`
-  # (RenderedEmail, for render/compose) or `:document` (parsed document, for parse).
   def initialize(payload:, label:, response: :email)
     @payload = payload
     @label = label
@@ -44,7 +42,6 @@ class ReactEmailRails::RenderModes::Subprocess
     end
   end
 
-  # Shared by Persistent#capture so the transport-error messages live in one place.
   def with_capture_rescues
     yield
   rescue Timeout::Error

data/lib/react_email_rails/render_protocol.rb

@@ -6,7 +6,6 @@ module ReactEmailRails
   module RenderProtocol
     extend(self)
 
-    # Callers keep their own rescue to also cover failures obtaining the result.
     def healthy_result?(result)
       result.status.success? && compatible_response?(JSON.parse(result.stdout))
     end

data/lib/react_email_rails/rendered_email.rb

@@ -1,5 +1,4 @@
 module ReactEmailRails
-  # `warnings` are non-fatal (document nodes nothing rendered); empty for component renders.
   RenderedEmail = Data.define(:html, :text, :warnings) do
     def initialize(html:, text:, warnings: [])
       super

data/lib/react_email_rails/shared_props.rb

@@ -1,5 +1,3 @@
-# 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
 
@@ -7,8 +5,6 @@ class ReactEmailRails::SharedProps
     @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?
@@ -32,8 +28,6 @@ class ReactEmailRails::SharedProps
     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
 

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/react_email_rails.rb

@@ -27,6 +27,7 @@ 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/preview_live_reload")
 require_relative("react_email_rails/railtie")
 
 module ReactEmailRails
@@ -46,7 +47,6 @@ module ReactEmailRails
       perform(payload:, label: component, kind: "email", component:)
     end
 
-    # The document is sent verbatim (keys are structural); only context is key-transformed, like props.
     def compose(type:, document:, context: {}, preview: nil)
       payload = {
         kind: "document",
@@ -59,7 +59,6 @@ module ReactEmailRails
       perform(payload:, label: type, kind: "document", type:)
     end
 
-    # 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",
@@ -90,7 +89,6 @@ module ReactEmailRails
       raise
     end
 
-    # Markdown is converted renderer-side, not here; both inputs are sent as-is.
     def parse_source(html:, markdown:)
       if !html.nil? && !markdown.nil?
         raise(ArgumentError, "ReactEmailRails.parse accepts only one of html: or markdown:")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Supertape
@@ -154,6 +154,7 @@ files:
 - lib/react_email_rails/action_mailer.rb
 - lib/react_email_rails/configuration.rb
 - lib/react_email_rails/mailer_context.rb
+- lib/react_email_rails/preview_live_reload.rb
 - lib/react_email_rails/props_resolver.rb
 - lib/react_email_rails/railtie.rb
 - lib/react_email_rails/render_error.rb