npm / mjml
mjml
What changed in mjml 4 to 5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
12 breaking1 security5 new APIs and options1 performance2 behavior and defaults2 tooling15 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmjml 527 changes
Breaking changes 11
The CLI include options have stricter behavior; users must explicitly allow includes rather than relying on implicit include behavior.
The body HTML tag is generated under mj-body rather than by the global skeleton, changing the outer HTML structure.
HTML minification now uses htmlnano instead of html-minifier, producing more aggressively minified output; custom minifier options need to be remapped.
Includes are ignored by default, so projects must explicitly allow them.
The background-color attribute no longer applies to the body tag and instead applies only to the child div.
The class attribute is applied to the body tag rather than the child div, which can affect external CSS targeting.
inner-padding is now applied to all clients rather than only Outlook.
Its build and minification pipeline now uses new minifiers; direct imports or reliance on legacy build scripts may see behavior and bundle shape changes.
The standalone migration tool is removed, so MJML 5 can no longer automatically migrate very old MJML syntax on the fly.
Node 20, 22, and 24 are the supported CI versions; Node 16 and 18 are effectively deprecated or unsupported.
The noMigrateWarn option is removed along with the migration helper.
Security 1
Resolved numerous production security vulnerabilities.
New APIs and options 4
Adds a gutter attribute to add space between columns.
Adds a border attribute to mj-social-element.
A new option explicitly controls where includes can be loaded from outside of a templates filePath.
The id attribute is now available on mj-body.
Performance 1
Beautification now uses Biome instead of Prettier, addressing slow calls on large MJML documents that caused 504 errors.
Behavior and default changes 2
All border-radius attributes now accept a string, allowing more flexible input and making values less strict for some components.
CSS minification uses cssnano presets wired via mjml-core, with the lite preset used by default; the default preset can be selected if your fonts don’t contain numerals.
Tooling 2
The CLI now emits warnings for denied mj-includes.
MJML uses js-beautify for beautification in mjml-core and mjml-browser, aiming for more stable, predictable output and better performance.
Fixes and other changes 6
Fixes a crash in strict validation when an mj-include is denied.
Fixed CLI watch behaviour.
CLI relative includePath entries are resolved against process.cwd() before being passed to mjml-core, so paths work when the template is in a subdirectory.
Fixes
mj-accordionelements being closed by default in new versions of Outlook.Fixes handling of async watch compilation in mjml-cli.
Template syntax is sanitized before PostCSS processing and restored afterward, affecting templates that place markers in CSS or style attributes.
mjml 411 changes
Breaking changes 1
mj-section no longer inherits attributes from context.
New APIs and options 1
Adds a gap between sections in mj-wrapper.
Fixes and other changes 9
Fixed allowed attributes not inheriting in mj-wrapper.
The font-family attribute is now respected.
The padding-x attribute is now respected.
Thumbnails are hidden when not supported.
Fixes border-radius, which was not working.
Fixes ico-padding-x, which was not working.
The align attribute is now respected.
The icon-height attribute is now respected.
The cellspacing attribute is now respected.