MJML CLI

5.0.1 · active · verified Sun Apr 19

The `mjml` package (which provides the `mjml-cli` functionality) is a robust, open-source framework designed to simplify the creation of responsive emails. It allows developers to build emails using a custom XML-like component language (MJML) that is then compiled into production-ready, semantic HTML, ensuring consistent rendering across various email clients. The current stable version, 5.0.1, introduces significant improvements in HTML output, minification, and security. Releases follow a steady cadence, with active development on minor versions and frequent alpha/beta cycles for major upgrades. Key differentiators include its declarative component-based approach, strong focus on email client compatibility, excellent documentation, and vibrant community support, collectively addressing the historical pain points of crafting reliable HTML emails. While the dedicated `mjml-cli` npm package is deprecated, the core `mjml` package provides the command-line interface functionality, enabling compilation, validation, and watch modes directly from the terminal.

Common errors

```
command not found: mjml
```
cause The `mjml` executable is not available in your system's PATH, either because the `mjml` package is not installed, it's installed locally but not globally, or the local `node_modules/.bin` directory is not sourced.

fix Install `mjml` globally (`npm install -g mjml`), or run it from your local `node_modules/.bin` directory (`./node_modules/.bin/mjml`), or add `./node_modules/.bin` to your PATH temporarily (`export PATH="$PATH:./node_modules/.bin"`).
```
Validation failed for file: my-email.mjml (Validation: strict)
```
cause You are compiling MJML with `--validationLevel strict` (or programmatically) and the MJML input contains invalid syntax, unknown components, or unsupported attributes according to the MJML specification.

fix Review the MJML file for errors indicated in the output. If the validation is too strict for your use case, change the validation level to `normal` (default) or `skip` using `--validationLevel normal` or `--validationLevel skip`.
```
Cannot find include path for file: components/header.mjml (from /path/to/base.mjml)
```
cause An `mj-include` statement within your MJML references a file that the MJML compiler cannot locate, likely due to an incorrect relative or absolute path, or the included file not existing.

fix Verify that the path specified in `mj-include` is correct relative to the including file or the configured `includePath` option. Ensure the included file exists and has the necessary read permissions. For v5, remember `mj-include` handling is stricter.

Warnings

deprecated The standalone `mjml-cli` npm package is officially deprecated and should no longer be used. Its functionality has been integrated directly into the main `mjml` package.
Fix: Uninstall `mjml-cli` if present (`npm uninstall mjml-cli`) and install the core `mjml` package (`npm install mjml`). All CLI commands are available via the `mjml` executable provided by the `mjml` package.
breaking MJML v5 replaced the legacy `html-minifier` and `js-beautify` libraries with `htmlnano` and `cssnano` for HTML and CSS optimization. This change can subtly alter the minified output compared to v4.
Fix: Carefully review your compiled HTML output after upgrading. Adjust `--config.minifyOptions` according to `htmlnano` and `cssnano` documentation if specific minification behavior is required. For CSS, `minifyCss` options now align with `cssnano` presets.
breaking The handling of `mj-include` and `ignoreIncludes` became stricter in MJML v5, enhancing security and predictability. Path resolution is now more rigorously enforced.
Fix: Ensure all `mj-include` paths are correct, relative, and accessible. If `ignoreIncludes` is used, verify its configuration and the `includePath` option. Test thoroughly, as previously tolerated incorrect paths might now cause compilation failures.
breaking The outer HTML structure, specifically the `<body>` tag, is now driven directly by `mj-body` in MJML v5. This restructuring can impact custom styles or external scripts relying on specific `<body>` attributes or placement.
Fix: Inspect the generated HTML for changes around the `<body>` tag. Adjust any custom CSS, JavaScript, or integration points that interact directly with the `<body>` element or its immediate children.
gotcha When MJML files contain templating variables (e.g., `{{ variable }}`) inside `<mj-style>` tags or inline `style="..."` attributes, the CSS minifiers (PostCSS/cssnano) might misinterpret these tokens, leading to incorrect CSS output or compilation errors.
Fix: Enable style sanitization by using `--config.sanitizeStyles true` in your CLI command or programmatic options. This option temporarily replaces template tokens during CSS processing and restores them afterward, preventing parsing issues.

Install

npm install mjml-cli npm
yarn add mjml-cli yarn
pnpm add mjml-cli pnpm

Imports

mjml2html
wrong:
```
const mjml2html = require('mjml').mjml2html;
```
correct:
```
import { mjml2html } from 'mjml';
```
For programmatic usage in Node.js or browser environments, `mjml2html` is the primary function to compile MJML string to HTML. The `mjml-cli` npm package is deprecated; users should import directly from the `mjml` package.
MjmlError
```
import { MjmlError } from 'mjml';
```
Used for programmatic error handling, particularly when `mjml2html` encounters validation issues or other compilation problems, allowing for structured error capture.
Options
```
import type { Options } from 'mjml';
```
TypeScript type definition for the configuration object passed to the `mjml2html` function, enabling type-safe usage of options like `minify`, `beautify`, `validationLevel`, and `fonts`.

Quickstart

Demonstrates how to install the `mjml` package and use its command-line interface to compile an MJML file to HTML, including watching for file changes and applying custom minification options.

npm install mjml

# Create an MJML file, e.g., 'template.mjml'
# <mjml>
#   <mj-body>
#     <mj-section>
#       <mj-column>
#         <mj-text>Hello from MJML!</mj-text>
#         <mj-button href="https://mjml.io">Learn More</mj-button>
#       </mj-column>
#     </mj-section>
#   </mj-body>
# </mjml>

# Compile MJML to HTML and output to a file
./node_modules/.bin/mjml template.mjml -o output.html

# Alternatively, if 'mjml' is globally installed or in your PATH:
mjml template.mjml -o output.html

# Watch for changes in 'template.mjml' and recompile automatically
mjml --watch template.mjml --output watch-output.html

# Compile with custom options: minify HTML and specify CSS minification preset
mjml template.mjml --config.minify true --config.minifyOptions='{"minifyCss": "default"}' -o minified.html

view raw JSON →