{"id":14707,"library":"mjml-cli","title":"MJML CLI","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/mjmlio/mjml","tags":["javascript"],"install":[{"cmd":"npm install mjml-cli","lang":"bash","label":"npm"},{"cmd":"yarn add mjml-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add mjml-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The `mjml-cli` package is deprecated. The CLI functionality described in the provided context is now entirely provided by the main `mjml` package.","package":"mjml","optional":false}],"imports":[{"note":"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.","wrong":"const mjml2html = require('mjml').mjml2html;","symbol":"mjml2html","correct":"import { mjml2html } from 'mjml';"},{"note":"Used for programmatic error handling, particularly when `mjml2html` encounters validation issues or other compilation problems, allowing for structured error capture.","symbol":"MjmlError","correct":"import { MjmlError } from 'mjml';"},{"note":"TypeScript type definition for the configuration object passed to the `mjml2html` function, enabling type-safe usage of options like `minify`, `beautify`, `validationLevel`, and `fonts`.","symbol":"Options","correct":"import type { Options } from 'mjml';"}],"quickstart":{"code":"npm install mjml\n\n# Create an MJML file, e.g., 'template.mjml'\n# <mjml>\n#   <mj-body>\n#     <mj-section>\n#       <mj-column>\n#         <mj-text>Hello from MJML!</mj-text>\n#         <mj-button href=\"https://mjml.io\">Learn More</mj-button>\n#       </mj-column>\n#     </mj-section>\n#   </mj-body>\n# </mjml>\n\n# Compile MJML to HTML and output to a file\n./node_modules/.bin/mjml template.mjml -o output.html\n\n# Alternatively, if 'mjml' is globally installed or in your PATH:\nmjml template.mjml -o output.html\n\n# Watch for changes in 'template.mjml' and recompile automatically\nmjml --watch template.mjml --output watch-output.html\n\n# Compile with custom options: minify HTML and specify CSS minification preset\nmjml template.mjml --config.minify true --config.minifyOptions='{\"minifyCss\": \"default\"}' -o minified.html","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"<5.0.0 (for `mjml-cli` itself), All (when `mjml-cli` is used instead of `mjml`)"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"The handling of `mj-include` and `ignoreIncludes` became stricter in MJML v5, enhancing security and predictability. Path resolution is now more rigorously enforced.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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\"`).","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.","error":"command not found: mjml"},{"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`.","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.","error":"Validation failed for file: my-email.mjml (Validation: strict)"},{"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.","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.","error":"Cannot find include path for file: components/header.mjml (from /path/to/base.mjml)"}],"ecosystem":"npm"}