### Install Editor Packages

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Install the necessary packages for @react-email/editor and @tiptap/core. These are required for basic editor document rendering.

```sh
npm i @react-email/editor @tiptap/core
```

--------------------------------

### Install npm package and React Email dependencies

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Manually install the necessary npm packages if you prefer not to use the installer. This includes the gem itself and core React Email libraries.

```shell
npm i react-email-rails @react-email/render @react-email/components react react-dom
```

--------------------------------

### Install Markdown Parsing Package

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Install the 'marked' package to enable parsing Markdown content. Markdown will be converted to HTML first, then parsed by the Tiptap parser.

```sh
npm i marked
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/heysupertape/react-email-rails/blob/main/CONTRIBUTING.md

Install Ruby gem dependencies and Node.js dependencies for the Vite package.

```sh
bundle install
cd vite && pnpm install
```

--------------------------------

### Install react-email-rails Gem

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Add the react-email-rails gem to your Gemfile and run bundle install.

```ruby
gem "react-email-rails"
```

--------------------------------

### Install HTML Parsing Packages

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Install @tiptap/html and happy-dom to enable parsing HTML into documents. This is needed if you want to convert HTML content into the editor's document format.

```sh
npm i @tiptap/html happy-dom
```

--------------------------------

### Welcome Email Component Using Layout

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

An example of a 'Welcome' email component that utilizes the 'EmailLayout' for consistent structure. It demonstrates how to import and use layout components.

```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>
  )
}
```

--------------------------------

### Generate react-email-rails Installer

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Run the generator to set up react-email-rails in your Rails application. This creates an initializer, installs JS dependencies, and configures Vite.

```shell
bundle install
bin/rails generate react_email_rails:install
```

--------------------------------

### Broadcast Document Renderer Example

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Defines extensions, transforms the document by adding a header, and provides preview text for a broadcast document type.

```typescript
import { StarterKit } from "@react-email/editor/extensions"
import { EmailTheming } from "@react-email/editor/plugins"

export function buildExtensions(context) {
  return [StarterKit, EmailTheming]
}

export function transformDocument(document, context) {
  const header = {
    type: "heading",
    attrs: { level: 1 },
    content: [{ type: "text", text: context.brandName }],
  }
  const themeIndex = document.content.findIndex((node) => node.type === "globalContent")
  const at = themeIndex + 1
  return {
    ...document,
    content: [...document.content.slice(0, at), header, ...document.content.slice(at)],
  }
}

export function getPreview(context) {
  return context.previewText
}
```

--------------------------------

### Deep Merged Props Example

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Illustrates the resulting props after a deep merge operation, showing how nested properties are combined.

```ruby
{ settings: { theme: "dark", locale: "en" } }
```

--------------------------------

### Parsing Markdown Content

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Use the `markdown:` option when your source emits Markdown. Ensure `marked` is installed with its HTML peers. Pass only one of `html:` or `markdown:`.

```ruby
document = ReactEmailRails.parse(
  type: "broadcast",
  markdown: "# Welcome\n\nThanks for signing up, **Ada**.",
  context: { brand_name: "Acme" },
)
```

--------------------------------

### Add Vite Plugin for React Email

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Configure your Vite setup to include the react-email-rails plugin for development rendering.

```typescript
import { defineConfig } from "vite"
import { reactEmailRails } from "react-email-rails"

export default defineConfig({
  plugins: [reactEmailRails()],
})
```

--------------------------------

### Override Shared Props with Per-Mail Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Per-mail props take precedence over shared props. This example shows how to override the `app_name` prop defined in shared props.

```ruby
mail(
  to: account.email,
  subject: "Welcome",
  react: {
    app_name: "Acme Pro",
  },
)
```

--------------------------------

### Prepare and Tag a Release

Source: https://github.com/heysupertape/react-email-rails/blob/main/CONTRIBUTING.md

Automates the process of preparing and tagging a new release (patch, minor, or major) after updating the version and changelog.

```sh
bin/release
```

--------------------------------

### Generate with Custom Path and Extension

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Override the default component directory or extension during generation using flags.

```sh
bin/rails generate react_email_rails:email Account welcome --emails-path=app/emails --extension=jsx
```

--------------------------------

### Run Core Development Checks

Source: https://github.com/heysupertape/react-email-rails/blob/main/CONTRIBUTING.md

Execute essential checks for version synchronization, tests, and linting before submitting a pull request.

```sh
ruby scripts/check_version_sync.rb
bin/test
bin/lint
cd vite && pnpm run build
```

--------------------------------

### Configure Render Options

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Pass options to @react-email/render to configure HTML and text output. Keys are camelized before 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
```

--------------------------------

### Run Rails Asset Precompilation

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Execute the standard Rails asset precompilation task, which includes the react-email-rails build hook.

```shell
bin/rails assets:precompile
```

--------------------------------

### Configure Standalone Builds

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Set `standalone: false` to use a smaller SSR-style bundle when your runtime ships `node_modules`.

```typescript
reactEmailRails({
  standalone: false,
})
```

--------------------------------

### Sync Version to Vite Package

Source: https://github.com/heysupertape/react-email-rails/blob/main/CONTRIBUTING.md

Synchronize the Ruby gem version and renderer protocol version into the Vite package. Run this after changing version files.

```sh
cd vite && pnpm run sync:version
```

--------------------------------

### Configure Multiple Document Extensions

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Use the 'extension' property within the 'documents' option to specify multiple file extensions for your document renderers.

```ts
reactEmailRails({
  documents: {
    extension: [".document.ts", ".document.tsx"],
  },
})
```

--------------------------------

### Run Renderer Build Directly

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Manually trigger the renderer build process for react-email-rails.

```shell
bin/rails react_email_rails:build
```

--------------------------------

### Switch to Persistent Render Mode

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Enable persistent render mode for faster rendering in render-heavy scenarios by keeping a long-lived Node child process.

```ruby
ReactEmailRails.configure do |config|
  config.render_mode = :persistent
end
```

--------------------------------

### Configure Custom Email Directory

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Use a custom directory for email components by specifying the `emails.path` option.

```typescript
reactEmailRails({
  emails: "app/emails",
})
```

--------------------------------

### Generate Mailer and React Email Component

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Use this command to generate a new mailer and its corresponding React Email component. It follows the standard Rails generator format.

```sh
bin/rails generate react_email_rails:email Account welcome
```

--------------------------------

### Configure Custom Email Extensions

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Specify custom file extensions for email components using the `emails.extension` option.

```typescript
reactEmailRails({
  emails: {
    extension: [".email.tsx", ".email.jsx"],
  },
})
```

--------------------------------

### Rendering a Stored Document

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Composes and renders an email from a previously stored document Hash.

```ruby
rendered = ReactEmailRails.compose(type: "broadcast", document: broadcast.body)
```

--------------------------------

### Specify Explicit Component and Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Manually specify the component name and its props when the default inference does not match or when you need more control.

```ruby
mail(
  to: account.email,
  subject: "Welcome",
  react: "accounts/welcome",
  props: {
    account: {
      name: account.name,
    },
  },
)
```

--------------------------------

### Enable Editor Documents in Vite Config

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Enable the 'documents' option in your Vite configuration file to activate editor document rendering. This uses default paths and extensions unless otherwise specified.

```ts
import { defineConfig } from "vite"
import { reactEmailRails } from "react-email-rails"

export default defineConfig({
  plugins: [reactEmailRails({ documents: true })],
})
```

--------------------------------

### Configure Vite with MDX for Document Renderers

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Integrate MDX support into the Vite pipeline specifically for isolated document renderers by adding MDX plugin to the 'vite' option within reactEmailRails configuration.

```ts
import mdx from "@mdx-js/rollup"
import { defineConfig } from "vite"
import { reactEmailRails } from "react-email-rails"

export default defineConfig({
  plugins: [
    reactEmailRails({
      documents: true,
      vite: {
        plugins: [mdx()],
      },
    }),
  ],
})
```

--------------------------------

### Report Render Errors

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Implement an error reporting callback to handle failures before exceptions are re-raised. The callback receives the error and render context.

```ruby
ReactEmailRails.configure do |config|
  config.on_render_error = ->(error, **context) {
    Rails.error.report(error, context:)
  }
end
```

--------------------------------

### Pass Props to React Component

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Demonstrates passing data from the mailer to the React component via the 'react:' hash. The keys in the hash become props for the component.

```ruby
mail(
  to: account.email,
  subject: "Welcome",
  react: {
    account: {
      name: account.name,
    },
  },
)
```

--------------------------------

### Add Email-Only Vite Plugins

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Integrate custom Vite plugins for email component transformations by adding them to the `vite.plugins` option.

```typescript
import mdx from "@mdx-js/rollup"
import { defineConfig } from "vite"
import { reactEmailRails } from "react-email-rails"

export default defineConfig({
  plugins: [
    reactEmailRails({
      vite: {
        plugins: [mdx()],
      },
    }),
  ],
})
```

--------------------------------

### Deliver Email

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Deliver the generated email using standard Action Mailer delivery methods. Pass any required parameters to the mailer.

```ruby
AccountMailer.with(account: current_account).welcome.deliver_later
```

--------------------------------

### Verify Renderer Health

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Check if the react-email-rails renderer is functioning correctly and if the npm package version matches the gem version.

```shell
bin/rails react_email_rails:verify
```

--------------------------------

### Configure Custom Document Directory

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Specify a custom directory for editor document renderers using the 'documents' option in the reactEmailRails plugin configuration.

```ts
reactEmailRails({
  documents: "app/documents",
})
```

--------------------------------

### Use Instance Variables as Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Enable `use_react_instance_props` to automatically pass mailer instance variables as props to the React component when using `react: true`.

```ruby
class AccountMailer < ApplicationMailer
  use_react_instance_props

  def welcome
    @account = params.fetch(:account)

    mail(to: @account.email, subject: "Welcome", react: true)
  end
end
```

--------------------------------

### Subscribe to Render Notifications

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Listen for 'render.react-email-rails' events using ActiveSupport::Notifications to log render details like component, duration, and HTML size.

```ruby
ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
  Rails.logger.info(
    "[react-email-rails] Rendered #{event.payload[:component]} " \
      "(#{event.duration.round}ms, #{event.payload[:html_bytes]} bytes)",
  )
end
```

--------------------------------

### Render Inferred Component with No Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Use `react: true` to render the component inferred from the mailer and action. This is useful for emails that do not require any specific props.

```ruby
mail(to: account.email, subject: "Welcome", react: true)
```

--------------------------------

### Set Prop Transformation

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Configure how Ruby prop keys are transformed for React components. Use :none to preserve serialized keys.

```ruby
ReactEmailRails.configure do |config|
  config.transform_props = :none
end
```

--------------------------------

### Composing a Broadcast Email

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Composes an email using the 'broadcast' type, document body, and context. Returns an object with html and text representations of the email.

```ruby
broadcast = Broadcast.find(params[:id])

rendered = ReactEmailRails.compose(
  type: "broadcast",
  document: broadcast.body,
  context: { brand_name: "Acme", preview_text: broadcast.subject },
  preview: broadcast.subject,
)

rendered.html # => "<!DOCTYPE html>..."
rendered.text # => "ACME\n\n..."
```

--------------------------------

### Email Layout Component

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

A reusable React component for structuring emails, providing a consistent layout with HTML, Body, and Container elements. This serves as a base for individual email components.

```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>
  )
}
```

--------------------------------

### Configure React Email Rails Defaults

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Override default Rails-side settings for mailer behavior, prop handling, rendering mode, timeouts, and error hooks.

```ruby
ReactEmailRails.configure do |config|
  # config.render_mode = :persistent
end
```

--------------------------------

### Debugging Dropped Content with Notifications

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Subscribe to the `render.react-email-rails` notification to capture warnings about dropped node types. This helps identify mismatches between extensions and the document schema.

```ruby
ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|
  warnings = event.payload[:warnings]
  raise "dropped #{warnings.sum { _1[:count] }}: #{warnings.map { _1[:type] }.join(", ")}" if warnings
end
```

--------------------------------

### Parsing HTML into a Document Hash

Source: https://github.com/heysupertape/react-email-rails/blob/main/docs/editor.md

Parses HTML content into a document Hash format suitable for storage, using the 'broadcast' type and provided context. Raises ReactEmailRails::RenderError on failure.

```ruby
document = ReactEmailRails.parse(
  type: "broadcast",
  html: params[:body_html],
  context: { brand_name: "Acme" },
)

broadcast.update!(body: document)
```

--------------------------------

### Update Mailer to Pass Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Modify the generated mailer to pass necessary data as props to the React component. Ensure the 'react:' hash includes the data.

```ruby
class AccountMailer < ApplicationMailer
  def welcome
    account = params.fetch(:account)

    mail(
      to: account.email,
      subject: "Welcome",
      react: {
        account: {
          name: account.name,
        },
      },
    )
  end
end
```

--------------------------------

### Share Props Across Mailers

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Define shared props that will be merged into all `react:` emails for a mailer and its subclasses. This is useful for common data like application names.

```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
```

--------------------------------

### Sharing Props Inside an Action

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Share props within an action before calling 'mail' to include them in the email's React component context. This allows dynamic prop sharing based on action logic.

```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
```

--------------------------------

### Programmatic Renderer Health Check

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Check the health of the react-email-rails renderer programmatically within a Rails application. This check is scoped to production and Sidekiq processes to avoid unnecessary overhead.

```ruby
Rails.application.config.after_initialize do
  if Rails.env.production? && Sidekiq.server? && !ReactEmailRails.healthy?
    Rails.logger.error "[react-email-rails] renderer verification failed"
  end
end
```

--------------------------------

### React Email Component with Mailer and Message Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

A React component that utilizes the injected 'mailer' and 'message' props. These props provide context about the mailer action and the email message itself.

```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>
  )
}
```

--------------------------------

### Deep Merging Shared Props

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Enable deep merging of shared props by passing 'deep_merge: true' to the 'mail' method. This merges nested hashes instead of replacing them, useful for combining configuration objects.

```ruby
react_email_share do
  { settings: { theme: "light", locale: "en" } }
end

mail(
  to: account.email,
  subject: "Welcome",
  react:
    {
      settings: {
        theme: "dark",
      },
    },
  deep_merge: true,
)
```

--------------------------------

### Conditional Shared Props with react_email_share

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Use react_email_share with filter options like 'only', 'except', 'if', and 'unless' to conditionally share props. This is useful for sharing props based on specific email types or conditions.

```ruby
react_email_share only: [:welcome, :reactivation] do
  { promotion: params.fetch(:promotion) }
end

react_email_share if: :account_active? do
  { account: { name: params.fetch(:account).name } }
end
```

--------------------------------

### Edit React Email Component

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Define the React component to receive and display the props passed from the mailer. Ensure type safety with TypeScript props.

```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 Component Props Definition

Source: https://github.com/heysupertape/react-email-rails/blob/main/README.md

Define the expected props for your React Email component using TypeScript. This ensures type safety when receiving data from the mailer.

```tsx
type WelcomeProps = {
  account: {
    name: string
  }
}

export default function Welcome({ account }: WelcomeProps) {
  // ...
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.