mjml-cli

library5.0.1jsnpmunverified

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.

communication

npm install mjml-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MJML-CLI

mjml-cli

communicationjavascriptv5.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mjml2html

✓ import { mjml2html } from 'mjml';

✗ const mjml2html = require('mjml').mjml2html;

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

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

mjml --version

Debug

Known issues

deprecatedThe 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.

affects: <5.0.0 (for `mjml-cli` itself), All (when `mjml-cli` is used instead of `mjml`)

breakingMJML 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.

affects: >=5.0.0

breakingThe 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.

affects: >=5.0.0

breakingThe 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.

affects: >=5.0.0

gotchaWhen 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.

affects: >=5.0.0

Errors

Common errors & fixes

command not found: mjml

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)

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)

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.

Upgrade

Version history

5.0.1latest on npm

Audit

Dependencies

mjmlrequiredThe `mjml-cli` package is deprecated. The CLI functionality described in the provided context is now entirely provided by the main `mjml` package.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mjmlio/mjml ↗

packagehttps://www.npmjs.com/package/mjml-cli ↗

homepagehttps://mjml.io ↗