{"id":13555,"library":"mjml-parser-xml","title":"MJML XML Parser","description":"mjml-parser-xml is a fundamental, internal package within the MJML ecosystem, currently at stable version 5.0.1. Its primary function is to parse MJML (Mailjet Markup Language) XML strings into an Abstract Syntax Tree (AST) or a similar structured JavaScript object representation. While this package is not typically accessed directly by end-users, who generally interact with the higher-level `mjml` package and its `mjml2html` function, it is a critical component that underpins the entire MJML conversion process. The parser translates MJML's declarative, semantic XML-like syntax into an intermediate format that the MJML engine can then process and render into robust, responsive HTML. The MJML project maintains an active and consistent development cadence, with frequent updates across its monorepo, including alpha and beta releases for major versions, ensuring ongoing compatibility with evolving email client standards and web practices.","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-parser-xml","lang":"bash","label":"npm"},{"cmd":"yarn add mjml-parser-xml","lang":"bash","label":"yarn"},{"cmd":"pnpm add mjml-parser-xml","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"MJMLParser is the default export of this package and should be imported without curly braces.","wrong":"import { MJMLParser } from 'mjml-parser-xml';","symbol":"MJMLParser","correct":"import MJMLParser from 'mjml-parser-xml';"},{"note":"For CommonJS environments, the default export is directly assigned. MJML v5 targets Node.js 20+, so ESM is preferred.","wrong":"const { MJMLParser } = require('mjml-parser-xml');","symbol":"MJMLParser","correct":"const MJMLParser = require('mjml-parser-xml');"}],"quickstart":{"code":"import MJMLParser from 'mjml-parser-xml';\n\nconst mjmlString = `\n  <mjml>\n    <mj-body>\n      <mj-section>\n        <mj-column>\n          <mj-text font-size=\"20px\" color=\"#F45E43\">Hello MJML World!</mj-text>\n        </mj-column>\n      </mj-section>\n    </mj-body>\n  </mjml>\n`;\n\ntry {\n  // Parse the MJML string into an AST (Abstract Syntax Tree) object\n  const ast = MJMLParser(mjmlString, {\n    // Optional configurations\n    keepComments: false, // Do not keep comments in the parsed output\n    filePath: './templates', // Base path for mj-include directives\n  });\n\n  console.log('Successfully parsed MJML to AST:');\n  console.log(JSON.stringify(ast, null, 2));\n\n  // Example of accessing a node (simplified, actual AST structure is more complex)\n  if (ast && ast.children && ast.children.length > 0) {\n    const firstBodyChild = ast.children[0];\n    console.log('\\nFirst child of mj-body:', firstBodyChild.tagName);\n  }\n\n} catch (error) {\n  console.error('Error parsing MJML:', error);\n}","lang":"typescript","description":"This quickstart demonstrates how to import the `MJMLParser` and use it to convert a raw MJML string into its corresponding Abstract Syntax Tree (AST) object, illustrating basic parsing functionality and options."},"warnings":[{"fix":"Review all `mj-include` paths and ensure they are relative to the `filePath` option passed to the parser or are explicitly allowed. Use `mjml.config.js` for global configuration if applicable.","message":"The handling of `<mj-include>` and `ignoreIncludes` has become stricter in MJML v5. This may lead to parsing errors if include paths are not correctly configured or if unauthorized file access is attempted.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Adjust any tools or tests that depend on precise whitespace or formatting of the generated HTML. Minification options can be configured via `.mjmlconfig.js`.","message":"MJML v5 has replaced legacy HTML/CSS minifiers (`html-minifier`, `js-beautify`) with `htmlnano` and `cssnano`. While `mjml-parser-xml` itself focuses on XML parsing, changes in the overall minification pipeline (driven by `mjml-core`) mean that the *final rendered HTML* will be more aggressively minified. This can affect workflows that rely on exact HTML formatting, diffing raw HTML, or parsing by regular expressions.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update any code or stylesheets that rely on the previous default `<body>` tag structure or its attributes. The `mj-body` component now controls its own `<body>` generation.","message":"The outer HTML structure has been restructured in MJML v5, with the `<body>` tag now driven by `mj-body` rather than a global skeleton. This affects the root HTML structure produced after parsing and rendering.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Avoid using `<` directly in `mj-raw` tags where it might be ambiguous. Consider using `&lt;` for the less-than entity or reordering comparisons (e.g., `10 >= value;`) if possible.","message":"The underlying XML parser (`htmlparser2`) can misinterpret the `<` character within `mj-raw` tags as an opening HTML tag, causing the parser to break and leave subsequent MJML unparsed. This is particularly problematic in templating contexts (e.g., `var value <= 10;`).","severity":"gotcha","affected_versions":">=4.x"},{"fix":"Manually review and update older MJML templates to conform to MJML v4 or v5 syntax before upgrading. Consult the MJML v4 migration guide for guidance.","message":"MJML v5 has removed the automatic migration helper for very old MJML syntax (v3.x/early v4.x). Users upgrading from these older versions must now manually update their MJML code to conform to modern syntax, as automatic fixes will no longer be applied.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Ensure your development and deployment environments are running Node.js version 20 or higher.","message":"MJML 5 officially drops support for older Node.js versions, specifically Node 16 and 18, and now targets Node 20, 22, and 24 in its CI. Running `mjml-parser-xml` in unsupported Node.js environments may lead to unexpected behavior or errors.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'5.0.1':21 'abstract':36 'access':53 'across':126 'activ':118 'alpha':130 'ast':39 'beta':132 'cadenc':122 'client':143 'compat':139 'compon':77 'consist':120 'convers':83 'critic':76 'current':17 'declar':90 'develop':121 'direct':54 'ecosystem':16 'email':142 'end':57 'end-us':56 'engin':103 'ensur':137 'entir':81 'evolv':141 'format':99 'frequent':124 'function':24,72 'fundament':10 'general':60 'higher':65 'higher-level':64 'html':112 'includ':129 'interact':61 'intermedi':98 'intern':11 'javascript':44,148 'languag':31 'level':66 'like':94 'mailjet':29 'maintain':116 'major':135 'markup':30 'mjml':1,5,15,28,67,82,88,102,114 'mjml-parser-xml':4 'mjml2html':71 'monorepo':128 'object':45 'ongo':138 'packag':12,49,68 'pars':27 'parser':3,6,86 'practic':147 'primari':23 'process':84,106 'project':115 'releas':133 'render':108 'represent':46 'respons':111 'robust':110 'semant':91 'similar':42 'stabl':19 'standard':144 'string':33 'structur':43 'syntax':37,95 'translat':87 'tree':38 'typic':52 'underpin':79 'updat':125 'user':58 'version':20,136 'web':146 'within':13 'xml':2,7,32,93 'xml-like':92","created_at":"2026-04-20T01:55:06.249092+00:00","updated_at":"2026-04-20T01:55:06.249092+00:00","problems":[{"fix":"Check for typos in MJML tag names. Ensure all custom components are correctly registered and available to the parser if using a custom setup.","cause":"The MJML input contains a tag that is not recognized as a valid MJML component.","error":"Error: Missing component for tag <unknown-tag>"},{"fix":"Verify that the `filePath` option passed to `MJMLParser` is correct and that the included file path is relative and accessible within the allowed directories. Ensure no '..' escapes outside the `filePath` are used.","cause":"MJML v5's stricter `mj-include` handling prevents resolution of the specified file path.","error":"Error: Cannot resolve mj-include path for file: 'path/to/my-partial.mjml'"},{"fix":"For ESM, use `import MJMLParser from 'mjml-parser-xml';`. For CommonJS, use `const MJMLParser = require('mjml-parser-xml');` and ensure your Node.js environment supports the module type being used.","cause":"This usually indicates a CommonJS module is trying to `require` an ESM-only package, or vice-versa, or the default export is not correctly imported.","error":"ReferenceError: MJMLParser is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://mjml.io","github":"https://github.com/mjmlio/mjml","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/mjml-parser-xml","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}