{"id":11337,"library":"mjml-browser","title":"MJML Browser Build","description":"MJML Browser (`mjml-browser`) is the client-side build of the MJML framework, designed for rendering responsive email templates directly within web browsers. This package, currently stable at version 5.0.1, allows developers to integrate MJML compilation into front-end applications, email builders, or interactive preview environments without requiring a Node.js backend. The MJML project maintains an active release cadence, frequently publishing alpha and beta versions alongside stable updates, indicating ongoing development and feature enhancements. While providing the core MJML rendering capabilities, `mjml-browser` differentiates itself from the full `mjml` Node.js package by its strict browser-only execution environment. This means certain server-side features, such as `mj-include` for modular templating and `.mjmlconfig` for custom components, are intentionally unsupported and ignored. Version 5 introduced significant changes, including a switch to `htmlnano` and `cssnano` for optimized HTML and CSS minification, which may affect output formatting compared to previous major versions.","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-browser","lang":"bash","label":"npm"},{"cmd":"yarn add mjml-browser","lang":"bash","label":"yarn"},{"cmd":"pnpm add mjml-browser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `mjml-browser` package typically provides a default export. While the README shows CommonJS `require()`, ESM `import` is widely used in modern browser build environments or when consuming from CDNs.","wrong":"import { mjml2html } from 'mjml-browser';","symbol":"mjml2html","correct":"import mjml2html from 'mjml-browser';"},{"note":"This CommonJS `require()` syntax is shown in the package's README for usage in environments supporting it, or after bundling for the browser.","symbol":"mjml2html","correct":"const mjml2html = require('mjml-browser');"}],"quickstart":{"code":"var mjml2html = require('mjml-browser');\n\nconst mjmlTemplate = `\n \n \n \n \n \n Welcome to MJML Browser!\n \n \n \n Learn More About MJML\n \n \n This demonstrates client-side MJML rendering. Remember, features like\n mj-include and .mjmlconfig for custom components are not supported\n in this browser-specific build. The output is responsive HTML suitable for email clients.\n \n \n \n \n \n`;\n\nconst options = {\n // Options for MJML compilation can be passed here.\n // 'validationLevel' can be 'skip', 'soft', or 'strict'.\n validationLevel: 'strict',\n // Other options specific to server-side Node.js MJML like 'filePath'\n // are not applicable to mjml-browser.\n};\n\ntry {\n const result = mjml2html(mjmlTemplate, options);\n\n if (result.errors.length > 0) {\n console.warn(\"MJML compilation encountered warnings/errors:\", result.errors);\n }\n\n // In a browser context, you would typically inject `result.html`\n // into an iframe or a designated div for preview.\n console.log(\"Successfully compiled MJML. Generated HTML (truncated):\\n\", result.html.substring(0, 700) + \"...\");\n\n // Example of displaying in a browser element:\n // document.getElementById('email-preview').innerHTML = result.html;\n\n} catch (e) {\n console.error(\"An error occurred during MJML compilation:\", e);\n}","lang":"javascript","description":"This quickstart compiles a simple MJML template into responsive HTML directly in the browser, demonstrating the core `mjml2html` function with basic options and error handling."},"warnings":[{"fix":"Adjust any tooling or tests that expect specific HTML/CSS formatting. If you previously passed minifier/beautifier flags, remap them to new `htmlnano`/`cssnano` configurations if applicable through MJML's options.","message":"Version 5.x replaced `html-minifier` and `js-beautify` with `htmlnano` and `cssnano` for minification. This may lead to differences in the generated HTML and CSS output, including more aggressive minification or altered formatting. Review any automated tests or processes that rely on exact HTML string comparisons.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Most standard MJML usage should adapt automatically. Custom components or highly specific post-processing might need adjustments to align with the new HTML structure.","message":"The outer HTML structure in version 5.x has been restructured, with the `` tag now being driven by `mj-body` instead of the global skeleton. This is an internal change that might affect advanced templating or custom component development.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"To use `mj-include` functionality, you must use the full `mjml` package in a Node.js environment. For `mjml-browser`, bundle your MJML into a single string before passing it to `mjml2html`.","message":"`mjml-browser` explicitly does not support `mj-include` tags, which are ignored during compilation. This means modularizing templates by including external MJML files will not work in the browser build.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If custom components are required, either compile your MJML using the full `mjml` package (which supports `.mjmlconfig`) in a Node.js environment, or find alternative ways to manage and inject custom HTML/MJML content directly into your templates before browser compilation.","message":"Custom MJML components defined via a `.mjmlconfig` file are not supported in `mjml-browser`. The package operates without file system access for configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use a module bundler to process your JavaScript, or use the ESM `import mjml2html from 'mjml-browser';` syntax if your environment and `mjml-browser` version support it. For direct browser use, ensure the script is loaded in a way that handles CommonJS, or use a pre-bundled ESM version if available.","message":"Using `require('mjml-browser')` directly in a modern browser environment (especially in modules with `type=\"module\"`) without a bundler like Webpack or Rollup will result in `ReferenceError: require is not defined`. This is because `require` is a CommonJS specific function not native to browsers.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"When targeting modern browsers, use `import mjml2html from 'mjml-browser';` and ensure your project is configured for ESM. If using older browser environments, a module bundler like Webpack, Rollup, or Browserify is required to transform CommonJS `require()` calls for browser compatibility.","cause":"`require` is a CommonJS function, not available natively in browser environments or ES Modules without a bundler.","error":"Uncaught ReferenceError: require is not defined"},{"fix":"Either concatenate your MJML templates into a single string before passing it to `mjml2html` in the browser, or perform MJML compilation including `mj-include` on the server-side using the full `mjml` package.","cause":"The `mjml-browser` package is designed for client-side use and intentionally ignores `mj-include` tags, as it cannot access local file systems.","error":"MJML: mj-include is not supported in mjml-browser"},{"fix":"Refactor your custom components to be standard MJML or plain HTML that can be directly embedded in your template string, or compile the MJML with custom components on the server-side using the full `mjml` package.","cause":"`mjml-browser` does not support custom components defined via a `.mjmlconfig` file due to its client-side nature and lack of file system access.","error":"Error: Custom component 'my-custom-component' not found."}],"ecosystem":"npm"}