LaraMJML

MJML rendering for Laravel Blade emails with a dedicated view engine, configurable MJML options, and predictable output for Mailables and Notifications.

Why LaraMJML

LaraMJML gives you a focused way to render MJML in Laravel without changing your email workflow:

• keeps Laravel Blade as the template layer
• compiles .mjml.blade.php layouts through an MJML view engine
• supports MJML runtime options from Laravel config
• works with Mailables and Notifications
• keeps rendering behavior deterministic across environments

Requirements

• PHP >=8.2
• Laravel 12.x or 13.x
• Node.js runtime with the mjml package installed

Installation

Install the package:

Install MJML in your Laravel app:

Publish the package config (optional):

Quick start

Create an MJML layout:

Save it as:

Create your email view with regular Blade inheritance:

Save it as:

Blade file rules

Use this hierarchy to avoid malformed MJML:

• the layout contains <mjml> and <mj-body>
• the layout filename includes .mjml.blade.php
• child views extend the MJML layout
• child views do not include .mjml in the filename

Correct:

Incorrect:

Use with Mailable

Send it:

Use with Notification

Dispatch it:

Configuration

The config/laramjml.php file controls:

• binary_path: path to the Node binary for MJML execution
• beautify: format generated HTML
• minify: minify generated HTML
• keep_comments: preserve MJML comments in output
• options: extra options passed to MJML

Environment variables:

Troubleshooting

• Empty or broken HTML: ensure only the layout contains <mjml> and <mj-body>
• MJML binary error: install mjml in the project and verify Node.js is available
• Malformed MJML exceptions: remove .mjml suffix from child views and keep it only on the layout

Testing

Run tests:

Validate MJML templates

Validate all MJML Blade layouts:

Validate specific paths:

Use a different validation level:

The command returns a non-zero exit code when at least one template fails validation, so it is ready for CI workflows.

Roadmap

• [ ] Add an optional Artisan install command (laramjml:install) to publish config in one step
• [ ] Add optional plain HTML fallback rendering when MJML conversion fails
• [x] Add built-in MJML lint/validate command for CI workflows
• [ ] Add a stub generator for MJML layout + starter email view
• [ ] Add snapshot tests for common MJML output patterns
• [ ] Add first-party examples for dark mode email patterns
• [ ] Add docs for queue-first email pipelines with MJML pre-rendering
• [ ] Add benchmarking docs and performance tips for high-volume mailing

Other packages

If you want to explore more of my packages:

• evanschleret/formforge
• evanschleret/formformclient (FormForge Client)
• evanschleret/laravel-user-presence
• evanschleret/laravel-typebridge

Open source

• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• License: LICENSE