### MJML Email Template Example
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
An example of an MJML template for an email confirmation, demonstrating the use of MJML components and ERB partials.
```erb
Hello World
Hello World
<%= render partial: "info", formats: [:html] %>
```
```erb
This is <%= @user.username %>
```
--------------------------------
### Install MJML Node Package and Scaffold Initializer
Source: https://context7.com/sighmon/mjml-rails/llms.txt
After adding the gem, install MJML via npm, yarn, or bun. Then, run the generator to scaffold the mjml initializer file.
```bash
bundle install
# Install MJML Node package (required unless using mrml)
npm install mjml # local (recommended)
npm install -g mjml # global (useful with Rails 7 + importmaps)
# or
yarn add mjml
# or
bun add mjml
# Scaffold the initializer
rails generate mjml:install
```
--------------------------------
### Install MJML NPM Package
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Install the MJML NPM package using npm, yarn, or bun. This is recommended for MJML v5 compatibility, especially with Rails 7 and importmaps.
```bash
# with npm
npm install mjml
# or install it globally (The best way for Rails 7.x.x with importmaps)
npm install -g mjml
# with yarn
yarn add mjml
# with bun
bun add mjml
```
--------------------------------
### Install mjml-rails Gem
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Add the mjml-rails gem to your Gemfile. If not using the Rust port (mrml), install the MJML Node package via npm, yarn, or bun.
```ruby
gem 'mjml-rails'
```
```ruby
# Optional: use pure-Ruby Rust port with no Node dependency
gem 'mrml'
```
--------------------------------
### Heroku package.json for MJML
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Example `package.json` file for a Heroku deployment that includes MJML as a dependency. This ensures Node.js and MJML are available during the build process.
```json
{
"name": "your-site",
"version": "1.0.0",
"description": "Now with MJML email templates!",
"main": "index.js",
"directories": {
"doc": "doc",
"test": "test"
},
"dependencies": {
"mjml": "^5.0.0"
},
"repository": {
"type": "git",
"url": "git+https://github.com/your-repo/your-site.git"
},
"keywords": [
"mailer"
],
"author": "Your Name",
"license": "ISC",
"bugs": {
"url": "https://github.com/sighmon/mjml-rails/issues"
},
"homepage": "https://github.com/sighmon/mjml-rails"
}
```
--------------------------------
### MJML Welcome Email Template
Source: https://context7.com/sighmon/mjml-rails/llms.txt
An example MJML template for a welcome email, including head attributes, body structure, and dynamic content using ERB.
```mjml
Welcome to ExampleApp!
Hello <%= @user.name %>!
Thanks for signing up. Your account is ready.
Go to Dashboard
```
--------------------------------
### MJML Email Partial
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
An example of an MJML email partial. Partials can be rendered within other MJML views.
```html
Hello <%= @recipient.name %>,
```
--------------------------------
### MJML Email Layout
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Example of an MJML email layout file. This defines the basic structure for MJML emails.
```html
<%= yield %>
```
--------------------------------
### Heroku Deployment: Configure Buildpack Order
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Ensure Node.js is provisioned before Ruby by setting the buildpack order. This is crucial for Heroku to correctly install MJML dependencies.
```bash
heroku buildpacks:set heroku/ruby
heroku buildpacks:add --index 1 heroku/nodejs
heroku buildpacks # verify order: 1. nodejs 2. ruby
```
--------------------------------
### MJML Mailer Layout Example
Source: https://context7.com/sighmon/mjml-rails/llms.txt
This is an example of a generated MJML layout file for an ActionMailer. It uses ERB's `yield` to insert the content from the mailer's view templates.
```mjml
<%# app/views/layouts/user_mailer.html.mjml — generated layout %>
<%= yield %>
```
--------------------------------
### Deliver MJML Email in Rails
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Example of how to trigger the delivery of an MJML-formatted email from anywhere within a Rails application.
```ruby
UserMailer.welcome(User.find(42)).deliver_now
```
--------------------------------
### MJML Email View
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
An example of an MJML email view template. This can be used for specific email content.
```html
<%= render partial: "to" %>
Something foo regarding bar!
```
--------------------------------
### Specify MJML-Rails Version for MJML 3.x
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Pin the mjml-rails gem to a specific version for MJML 3.x compatibility and install MJML 3.x globally.
```ruby
gem 'mjml-rails', '2.4.3'
```
```bash
npm install -g mjml@3.3.5
```
--------------------------------
### Add mjml-rails to Gemfile
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Include the mjml-rails gem in your application's Gemfile to start using MJML for email templates.
```ruby
gem 'mjml-rails'
```
--------------------------------
### Heroku Deployment: Add MJML to package.json
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Include MJML as a dependency in your Rails application's `package.json` file to ensure it's installed during the Heroku build process.
```json
{
"name": "my-app",
"version": "1.0.0",
"dependencies": {
"mjml": "^5.0.0"
}
}
```
--------------------------------
### Configure mjml-rails
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Customize mjml-rails behavior by setting options within the Mjml.setup block in config/initializers/mjml.rb. Options include template language, error handling, output beautification, minification, validation level, parser choice, binary path, supported version, caching, and custom fonts.
```ruby
# config/initializers/mjml.rb
Mjml.setup do |config|
# Template language used inside .mjml files (default: :erb)
# Other options: :haml, :slim (requires the respective gem)
config.template_language = :erb
# Raise ActionView::Template::Error on any render failure (default: true)
# Set false only when a plain-text fallback is always present
config.raise_render_exception = true
# Beautify output HTML via prettier (MJML v5) — default: true
config.beautify = true
# Minify output HTML via htmlnano/cssnano (MJML v5) — default: false
config.minify = false
# MJML validation strictness (default: 'strict')
# 'strict' — raises on any invalid tag/attribute
# 'soft' — renders what it can and silently drops invalid parts
config.validation_level = 'strict'
# Use mrml Rust gem instead of the Node.js mjml binary (default: false)
# When true, mjml_binary*, minify, beautify, and validation_level are ignored
config.use_mrml = false
# Path to a specific mjml binary (auto-detected by default)
config.mjml_binary = '/usr/local/bin/mjml'
# Expected version prefix — fails fast if a wrong version is installed
config.mjml_binary_version_supported = '5.'
# Cache compiled HTML in tmp/mjml_cache using SHA-256 fingerprint (default: false)
config.cache_mjml = true
# Override MJML default Google Fonts; pass empty hash to use system fonts only
config.fonts = {
Raleway: 'https://fonts.googleapis.com/css?family=Raleway',
Mononoki: 'https://cdn.jsdelivr.net/npm/@xz/fonts@1/serve/mononoki.min.css'
}
end
```
--------------------------------
### Heroku Deployment: Push to Heroku
Source: https://context7.com/sighmon/mjml-rails/llms.txt
After configuring buildpacks and dependencies, push your code to Heroku to deploy the application with MJML support.
```bash
git push heroku main
```
--------------------------------
### Direct MJML Compilation with Mjml::Parser
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Demonstrates standalone usage of Mjml::Parser to compile an MJML string directly to HTML, useful for testing or background jobs. Includes basic error handling for parse errors.
```ruby
mjml_source = <<~MJML
Hello from Parser!
MJML
begin
parser = Mjml::Parser.new('manual_render', mjml_source)
html = parser.render
puts html
rescue Mjml::Parser::ParseError => e
Rails.logger.error "MJML compile error: #{e.message}"
end
```
--------------------------------
### Heroku Buildpack Configuration
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Commands to set up Heroku buildpacks for an application that uses both Ruby and Node.js (for MJML). The Node.js buildpack is added at index 1 to ensure it runs first.
```bash
$ heroku buildpacks:set heroku/ruby
```
```bash
$ heroku buildpacks:add --index 1 heroku/nodejs
```
```bash
$ heroku buildpacks
```
--------------------------------
### Pin mjml-rails and MJML versions
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Use the Gemfile to pin `mjml-rails` and npm/yarn to pin the MJML version. This ensures compatibility between the gem and the MJML binary.
```bash
# Stay on MJML 4.x
# Gemfile: gem 'mjml-rails', '~> 4.16'
npm install mjml@4
# Use legacy MJML 3.x
# Gemfile: gem 'mjml-rails', '2.4.3'
npm install -g mjml@3.3.5
```
--------------------------------
### Configure Gemfile for MRML Renderer
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Add the 'mrml' gem to your Gemfile alongside 'mjml-rails' to enable the node-free Rust-based MJML rendering engine.
```ruby
# Gemfile
gem 'mjml-rails'
gem 'mrml', '~> 1.4'
```
--------------------------------
### Configure MJML-Rails to use MRML
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Set the `use_mrml` option to `true` in the MJML initializer to use the MRML gem, which includes pre-compiled Rust binaries for MJML and has no external JavaScript dependencies.
```ruby
# config/initializers/mjml.rb
Mjml.setup do |config|
config.use_mrml = true
end
```
--------------------------------
### Configure MRML Parsing in mjml-rails
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Set `use_mrml` to true in the initializer to enable MRML parsing. Other options like `mjml_binary`, `beautify`, `minify`, and `validation_level` are ignored when `use_mrml` is true.
```ruby
Mjml.setup do |config|
config.use_mrml = true
# mjml_binary, beautify, minify, validation_level are ignored when use_mrml is true
end
```
--------------------------------
### Add mjml-rails and mrml to Gemfile
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Include both `mjml-rails` and `mrml` gems in your Gemfile if you intend to use MRML for MJML rendering.
```ruby
gem 'mjml-rails'
gem 'mrml'
```
--------------------------------
### Configure MJML-Rails Settings
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Set MJML-Rails configuration options such as template language, error handling, minification, validation level, MRML usage, binary paths, fonts, and caching.
```ruby
Mjml.setup do |config|
# Use :haml as a template language
config.template_language = :haml
# Ignore errors silently
config.raise_render_exception = false
# Optimize the size of your emails
config.beautify = false
config.minify = true
# Render MJML templates with errors
config.validation_level = "soft"
# Use MRML instead of MJML, false by default
config.use_mrml = false
# Use custom MJML binary with custom version
config.mjml_binary = "/path/to/custom/mjml"
config.mjml_binary_version_supported = "3.3.5"
# Use default system fonts instead of google fonts
config.fonts = {}
# Uncomment this to enable template caching
# config.cache_mjml = true
end
```
--------------------------------
### Configure MJML Validation Level (Soft)
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Set `validation_level` to 'soft' and `raise_render_exception` to false for lenient validation. Invalid parts of templates will be silently dropped, and the method returns an empty string on total failure.
```ruby
# --- Soft: renders what it can; invalid parts are silently dropped ---
Mjml.setup do |config|
config.validation_level = 'soft'
config.raise_render_exception = false # returns "" on total failure instead of raising
end
```
--------------------------------
### Render MRML templates with Mjml::MrmlParser
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Use `Mjml::MrmlParser` to render MRML directly without spawning a Node process. Ensure proper error handling for potential MRML rendering issues.
```ruby
# Usage is identical to the standard parser — the handler switches automatically
mjml = 'MRML!'
parser = Mjml::MrmlParser.new('mrml_test', mjml)
html = parser.render # => compiled HTML, no Node process spawned
# Error handling
begin
bad_parser = Mjml::MrmlParser.new('bad', '')
bad_parser.render
rescue MRML::Error => e
puts "MRML error: #{e.message}"
end
```
--------------------------------
### Rails Mailer Configuration for MJML
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Configure an Action Mailer to send emails using both text and MJML formats.
```ruby
# ./app/mailers/user_mailer.rb
class UserMailer < ActionMailer::Base
def user_signup_confirmation
mail(to: "user@example.com", from: "app@example.com") do |format|
format.text
format.mjml
end
end
end
```
--------------------------------
### Enable and Manage MJML Template Caching
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Set `cache_mjml` to true in the initializer to cache compiled HTML. Compiled files are stored in `tmp/mjml_cache/`. Manually bust the cache using `FileUtils.rm_rf`.
```ruby
# Enable in initializer
Mjml.setup { |c| c.cache_mjml = true }
# Cache is populated transparently on first render and hit on subsequent ones.
# To manually bust the cache (e.g. in a deploy hook):
FileUtils.rm_rf(Rails.root.join('tmp', 'mjml_cache'))
# The Cache class can also be exercised in isolation:
cache = Mjml::Cache.new('user_mailer/welcome')
result = cache.cache { expensive_mjml_compilation } # block only called on cache miss
```
--------------------------------
### Configure Devise to Use Custom Mailer
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Update the Devise initializer to point to your custom mailer class, ensuring Devise uses it for sending emails.
```ruby
Devise.setup do |config|
config.mailer = 'DeviseMailer'
end
```
--------------------------------
### Specify MJML-Rails Version for MJML 2.x
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Pin the mjml-rails gem to a specific version for MJML 2.x compatibility.
```ruby
gem 'mjml-rails', '2.2.0'
```
--------------------------------
### Define MJML Email in Rails Mailer
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Configure an Action Mailer to render MJML templates. Ensure that `default.html.mjml` is available if `default.html.erb` is not present.
```ruby
class MyMailer < ActionMailer::Base
layout "default"
def foo_bar(user)
@recipient = user
mail(to: user.email, from: "app@example.com") do |format|
format.html # This will look for "default.html.erb" and then "default.html.mjml"
end
end
end
```
--------------------------------
### MJML Partial for Order Summary
Source: https://context7.com/sighmon/mjml-rails/llms.txt
An MJML partial template to display order summary details, designed to be rendered within another ERB or MJML view.
```erb
<%# app/views/order_mailer/_order_summary.html.erb %>
Order Summary
<% @order.items.each do |item| %>
<%= item.name %> × <%= item.quantity %> — <%= number_to_currency(item.price) %>
<% end %>
```
--------------------------------
### Specify MJML-Rails Version for MJML 4.x
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Pin the mjml-rails gem to a version compatible with MJML 4.x.
```ruby
gem 'mjml-rails', '~> 4.16'
```
--------------------------------
### Generate MJML Mailer
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Use the mjml:mailer generator to create an ActionMailer mailer with an MJML layout and ERB view stubs. This sets up the mailer to use the :mjml format handler for automatic compilation.
```bash
rails generate mjml:mailer UserMailer welcome reset_password
# creates: app/mailers/user_mailer.rb
# app/views/user_mailer/welcome.html.erb
# app/views/user_mailer/reset_password.html.erb
# app/views/layouts/user_mailer.html.mjml
```
--------------------------------
### Render ERB View into MJML Layout
Source: https://context7.com/sighmon/mjml-rails/llms.txt
An ERB view that renders a partial and includes MJML components, intended to be injected into an MJML layout via `<%= yield %>`.
```erb
<%# app/views/order_mailer/shipped.html.erb %>
<%= render partial: "order_summary", formats: [:html] %>
Your order #<%= @order.number %> has shipped!
Track Package
```
--------------------------------
### Configure MJML Validation Level (Strict)
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Set `validation_level` to 'strict' and `raise_render_exception` to true to have invalid MJML templates raise `ActionView::Template::Error`. This is the default behavior.
```ruby
# config/initializers/mjml.rb
# --- Strict (default): raises ActionView::Template::Error on invalid templates ---
Mjml.setup do |config|
config.validation_level = 'strict'
config.raise_render_exception = true
end
# In a mailer action, invalid templates surface as render-time exceptions:
begin
UserMailer.broken_email(user).deliver_now
rescue ActionView::Template::Error => e
Rails.logger.error "Email render failed: #{e.message}"
end
```
--------------------------------
### Check Resolved MJML Binary Path
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Use `Mjml.valid_mjml_binary` to see which MJML binary path was automatically discovered. The gem prioritizes custom paths, MRML, Bun, local npm/yarn, and finally global PATH.
```ruby
# Check which binary was resolved
puts Mjml.valid_mjml_binary
# => "/app/node_modules/.bin/mjml" (npm local install)
# => "bun run mjml" (bun install)
# => "/usr/local/bin/mjml" (global install)
# => nil (not found — error printed)
# Override with an explicit path
Mjml.setup do |config|
config.mjml_binary = Rails.root.join('node_modules', '.bin', 'mjml').to_s
config.mjml_binary_version_supported = '5.'
end
# Force re-detection (e.g. in tests)
Mjml.valid_mjml_binary = nil
Mjml.valid_mjml_binary # triggers fresh lookup
```
--------------------------------
### Define MJML Email in Rails Mailer
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Configure a Rails mailer to send emails with both plain text and MJML formats. The MJML format will be compiled by mjml-rails.
```ruby
class UserMailer < ActionMailer::Base
layout 'default'
def welcome(user)
@user = user
mail(to: user.email, from: 'app@example.com') do |format|
format.text
format.mjml
end
end
end
```
--------------------------------
### Devise MJML Reset Password Template
Source: https://context7.com/sighmon/mjml-rails/llms.txt
An MJML template for Devise's password reset instructions, using ERB to include dynamic links and user information.
```mjml
Hi <%= @resource.email %>,
Click below to reset your password. The link expires in 2 hours.
Reset Password
```
--------------------------------
### Override Devise Mailer for MJML
Source: https://github.com/sighmon/mjml-rails/blob/master/README.md
Customize the Devise mailer to send emails using MJML templates. This involves overriding methods like `reset_password_instructions` and specifying the MJML format in the `mail` block.
```ruby
# app/mailers/devise_mailer.rb
class DeviseMailer < Devise::Mailer
def reset_password_instructions(record, token, opts={})
@token = token
@resource = record
# Custom logic to send the email with MJML
mail(
template_path: 'devise/mailer',
from: "some@email.com",
to: record.email,
subject: "Custom subject"
) do |format|
format.text
format.mjml
end
end
end
```
--------------------------------
### MJML Layout for Shared Email Chrome
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Define a default MJML layout for emails, including head elements and body sections that wrap individual email content.
```mjml
<%= yield %>
© <%= Date.today.year %> ExampleApp
```
--------------------------------
### Override Devise Mailer for MJML
Source: https://context7.com/sighmon/mjml-rails/llms.txt
Subclass Devise's mailer to enable MJML templates for transactional emails like password resets. Ensure the mail method specifies both text and MJML formats.
```ruby
class DeviseMailer < Devise::Mailer
def reset_password_instructions(record, token, opts = {})
@token = token
@resource = record
mail(
template_path: 'devise/mailer',
from: 'noreply@example.com',
to: record.email,
subject: 'Reset your password'
) do |format|
format.text
format.mjml
end
end
end
```
=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.