MJML Browser Build

5.0.1 · active · verified Sun Apr 19

MJML Browser (`mjml-browser`) is the client-side build of the MJML framework, designed for rendering responsive email templates directly within web browsers. This package, currently stable at version 5.0.1, allows developers to integrate MJML compilation into front-end applications, email builders, or interactive preview environments without requiring a Node.js backend. The MJML project maintains an active release cadence, frequently publishing alpha and beta versions alongside stable updates, indicating ongoing development and feature enhancements. While providing the core MJML rendering capabilities, `mjml-browser` differentiates itself from the full `mjml` Node.js package by its strict browser-only execution environment. This means certain server-side features, such as `mj-include` for modular templating and `.mjmlconfig` for custom components, are intentionally unsupported and ignored. Version 5 introduced significant changes, including a switch to `htmlnano` and `cssnano` for optimized HTML and CSS minification, which may affect output formatting compared to previous major versions.

Common errors

```
Uncaught ReferenceError: require is not defined
```
cause `require` is a CommonJS function, not available natively in browser environments or ES Modules without a bundler.

fix When targeting modern browsers, use `import mjml2html from 'mjml-browser';` and ensure your project is configured for ESM. If using older browser environments, a module bundler like Webpack, Rollup, or Browserify is required to transform CommonJS `require()` calls for browser compatibility.
```
MJML: mj-include is not supported in mjml-browser
```
cause The `mjml-browser` package is designed for client-side use and intentionally ignores `mj-include` tags, as it cannot access local file systems.

fix Either concatenate your MJML templates into a single string before passing it to `mjml2html` in the browser, or perform MJML compilation including `mj-include` on the server-side using the full `mjml` package.
```
Error: Custom component 'my-custom-component' not found.
```
cause `mjml-browser` does not support custom components defined via a `.mjmlconfig` file due to its client-side nature and lack of file system access.

fix Refactor your custom components to be standard MJML or plain HTML that can be directly embedded in your template string, or compile the MJML with custom components on the server-side using the full `mjml` package.

Warnings

breaking Version 5.x replaced `html-minifier` and `js-beautify` with `htmlnano` and `cssnano` for minification. This may lead to differences in the generated HTML and CSS output, including more aggressive minification or altered formatting. Review any automated tests or processes that rely on exact HTML string comparisons.
Fix: Adjust any tooling or tests that expect specific HTML/CSS formatting. If you previously passed minifier/beautifier flags, remap them to new `htmlnano`/`cssnano` configurations if applicable through MJML's options.
breaking The outer HTML structure in version 5.x has been restructured, with the `<body>` tag now being driven by `mj-body` instead of the global skeleton. This is an internal change that might affect advanced templating or custom component development.
Fix: Most standard MJML usage should adapt automatically. Custom components or highly specific post-processing might need adjustments to align with the new HTML structure.
gotcha `mjml-browser` explicitly does not support `mj-include` tags, which are ignored during compilation. This means modularizing templates by including external MJML files will not work in the browser build.
Fix: To use `mj-include` functionality, you must use the full `mjml` package in a Node.js environment. For `mjml-browser`, bundle your MJML into a single string before passing it to `mjml2html`.
gotcha Custom MJML components defined via a `.mjmlconfig` file are not supported in `mjml-browser`. The package operates without file system access for configuration.
Fix: If custom components are required, either compile your MJML using the full `mjml` package (which supports `.mjmlconfig`) in a Node.js environment, or find alternative ways to manage and inject custom HTML/MJML content directly into your templates before browser compilation.
gotcha Using `require('mjml-browser')` directly in a modern browser environment (especially in modules with `type="module"`) without a bundler like Webpack or Rollup will result in `ReferenceError: require is not defined`. This is because `require` is a CommonJS specific function not native to browsers.
Fix: Use a module bundler to process your JavaScript, or use the ESM `import mjml2html from 'mjml-browser';` syntax if your environment and `mjml-browser` version support it. For direct browser use, ensure the script is loaded in a way that handles CommonJS, or use a pre-bundled ESM version if available.

Install

npm install mjml-browser npm
yarn add mjml-browser yarn
pnpm add mjml-browser pnpm

Imports

mjml2html
wrong:
```
import { mjml2html } from 'mjml-browser';
```
correct:
```
import mjml2html from 'mjml-browser';
```
The primary `mjml-browser` package typically provides a default export. While the README shows CommonJS `require()`, ESM `import` is widely used in modern browser build environments or when consuming from CDNs.
mjml2html
```
const mjml2html = require('mjml-browser');
```
This CommonJS `require()` syntax is shown in the package's README for usage in environments supporting it, or after bundling for the browser.

Quickstart

This quickstart compiles a simple MJML template into responsive HTML directly in the browser, demonstrating the core `mjml2html` function with basic options and error handling.

var mjml2html = require('mjml-browser');

const mjmlTemplate = `
  <mjml>
    <mj-body>
      <mj-section background-color="#f0f0f0">
        <mj-column>
          <mj-text font-size="24px" color="#333" align="center">
            Welcome to MJML Browser!
          </mj-text>
          <mj-image width="150px" src="https://mjml.io/assets/img/logo-mjml-compact.png" alt="MJML Logo" />
          <mj-button href="https://mjml.io" background-color="#414141" color="#ffffff" font-size="16px" padding="10px 25px">
            Learn More About MJML
          </mj-button>
          <mj-text font-size="14px" color="#666" padding-top="20px">
            This demonstrates client-side MJML rendering. Remember, features like
            <code>mj-include</code> and <code>.mjmlconfig</code> for custom components are not supported
            in this browser-specific build. The output is responsive HTML suitable for email clients.
          </mj-text>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
`;

const options = {
  // Options for MJML compilation can be passed here.
  // 'validationLevel' can be 'skip', 'soft', or 'strict'.
  validationLevel: 'strict',
  // Other options specific to server-side Node.js MJML like 'filePath'
  // are not applicable to mjml-browser.
};

try {
  const result = mjml2html(mjmlTemplate, options);

  if (result.errors.length > 0) {
    console.warn("MJML compilation encountered warnings/errors:", result.errors);
  }

  // In a browser context, you would typically inject `result.html`
  // into an iframe or a designated div for preview.
  console.log("Successfully compiled MJML. Generated HTML (truncated):\n", result.html.substring(0, 700) + "...");

  // Example of displaying in a browser element:
  // document.getElementById('email-preview').innerHTML = result.html;

} catch (e) {
  console.error("An error occurred during MJML compilation:", e);
}

view raw JSON →