Required dependencies

npm install mjml mjml-core mjml-preset-core mjml-validator mjml-parser-xml

If you use the CLI:

npm install mjml-cli

For browser builds, mjml-browser uses webpack with custom mocks — run its webpack config separately; it is not a runtime npm dependency for Node.js consumers.

No native modules, no pod install, no Android linking required for Node.js usage.

Project setup

1. Copy the source/ directory into your project root, e.g. as vendor/mjml/.

2. If your project uses TypeScript, add path aliases in tsconfig.json (the packages ship ES modules compiled via Babel):

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowJs": true,
    "esModuleInterop": true
  }
}

3. If using Babel (required for the .js ES-module source), ensure @babel/preset-env and @babel/plugin-proposal-class-properties are configured:

{
  "presets": [["@babel/preset-env", { "targets": { "node": "current" } }]],
  "plugins": ["@babel/plugin-proposal-class-properties"]
}

4. No mandatory environment variables. Optional env vars consumed by mjml-core:

   • MJML_CONFIG — path to a .mjmlconfig file (component registration overrides)

5. Import from the top-level mjml package (or source/mjml/src/index.js):

import mjml2html from 'mjml'

Public API

mjml2html

async function mjml2html(
  input: string,
  options?: {
    beautify?: boolean
    minify?: boolean
    validationLevel?: 'strict' | 'soft' | 'skip'
    filePath?: string
    fonts?: Record<string, string>
    keepComments?: boolean
    preprocessors?: Array<(xml: string) => string>
  }
): Promise<{ html: string; errors: Array<{ tagName: string; message: string; line: number }> }>

The primary entry point. Pass a raw MJML string; receive compiled HTML and a list of validation errors. Use validationLevel: 'skip' in production when templates are pre-validated to skip runtime checks.

MjBody

class MjBody extends BodyComponent {
  static componentName: 'mj-body'
  static allowedAttributes: {
    width: 'unit(px)'
    'background-color': 'color'
    id: 'string'
  }
  static defaultAttributes: { width: '600px' }
  getChildContext(): Record<string, unknown>
  getStyles(): Record<string, Record<string, string>>
  render(): string
}

The root body component. Extend this class when building custom wrapper components that need to participate in the child-context system (e.g., passing containerWidth downstream).

MjButton

class MjButton extends BodyComponent {
  static componentName: 'mj-button'
  static endingTag: true
  static allowedAttributes: Record<string, string>
  static defaultAttributes: Record<string, string>
}

A self-contained call-to-action button component. Register it via assignComponents if you are composing a custom preset without mjml-preset-core. The endingTag: true flag means the component wraps inner text content rather than child MJML components.

Accordion / AccordionElement / AccordionText / AccordionTitle

export { Accordion, AccordionElement, AccordionText, AccordionTitle } from 'mjml-accordion'

Four cooperating components for interactive disclosure widgets. Register all four together; Accordion is the parent, and the three sub-components must be declared as its allowed children in your dependency map.

Working examples

Scenario - Compile a minimal transactional email

Render a simple notification email to HTML and write it to disk.

import mjml2html from './vendor/mjml/src/index.js'
import fs from 'fs/promises'

const template = `
<mjml>
  <mj-head>
    <mj-title>Order Confirmed</mj-title>
    <mj-preview>Your order #1234 is confirmed.</mj-preview>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text font-size="20px" color="#333333">Hello, your order is confirmed!</mj-text>
        <mj-button href="https://example.com/orders/1234">View Order</mj-button>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>
`

const { html, errors } = await mjml2html(template, { validationLevel: 'soft' })

if (errors.length) {
  console.error('MJML validation errors:', errors)
}

await fs.writeFile('output.html', html, 'utf8')
console.log('Written output.html')

Scenario - Express route serving email preview

Serve compiled MJML as HTML from an Express endpoint for browser preview.

import express from 'express'
import mjml2html from './vendor/mjml/src/index.js'

const app = express()
app.use(express.json())

app.post('/preview-email', async (req, res) => {
  const { mjmlSource } = req.body as { mjmlSource: string }

  if (!mjmlSource) {
    return res.status(400).json({ error: 'mjmlSource is required' })
  }

  const { html, errors } = await mjml2html(mjmlSource, {
    beautify: true,
    validationLevel: 'soft',
  })

  if (errors.length > 0) {
    return res.status(422).json({ errors })
  }

  res.setHeader('Content-Type', 'text/html')
  res.send(html)
})

app.listen(3000, () => console.log('Preview server on :3000'))

Scenario - Register a custom component alongside preset-core

Use assignComponents and assignDependencies to add a custom component without replacing the full preset.

import mjml2htmlCore, { components, assignComponents } from './vendor/mjml-core/src/index.js'
import { dependencies, assignDependencies } from './vendor/mjml-validator/src/index.js'
import presetCore from './vendor/mjml-preset-core/src/index.js'
import { BodyComponent } from './vendor/mjml-core/src/index.js'

class MjCustomBanner extends BodyComponent {
  static componentName = 'mj-custom-banner'
  static endingTag = true
  static defaultAttributes = { color: '#ff0000' }
  render() {
    return `<div style="color:${this.getAttribute('color')}">${this.getContent()}</div>`
  }
}

assignComponents(components, {
  ...presetCore.components,
  'mj-custom-banner': MjCustomBanner,
})
assignDependencies(dependencies, {
  ...presetCore.dependencies,
  'mj-column': [...(presetCore.dependencies['mj-column'] ?? []), 'mj-custom-banner'],
})

const { html } = await mjml2htmlCore(
  `<mjml><mj-body><mj-section><mj-column>
     <mj-custom-banner color="#0055ff">Hello</mj-custom-banner>
   </mj-column></mj-section></mj-body></mjml>`,
  {}
)
console.log(html)

File walkthrough

• mjml/src/index.js - Bootstraps the compiler: loads mjml-core, attaches mjml-preset-core components and dependencies, then re-exports mjml2html as the async default.
• mjml-accordion/src/index.js - Re-exports all four accordion sub-classes for downstream registration.
• mjml-accordion/src/Accordion.js - Parent accordion container component with CSS toggle logic.
• mjml-accordion/src/AccordionElement.js - Individual collapsible row within an accordion.
• mjml-accordion/src/AccordionText.js - Body text content of an accordion element.
• mjml-accordion/src/AccordionTitle.js - Clickable title header of an accordion element.
• mjml-body/src/index.js - MjBody class; establishes containerWidth context for all children.
• mjml-body/src/helpers/preview.js - Renders the hidden preview-text <div> in the email body.
• mjml-browser/webpack.config.js - Webpack config that substitutes Node.js modules with browser-safe mocks.
• mjml-browser/browser-mocks/ - Stub implementations of fs, path, htmlnano, etc. for browser builds.
• mjml-button/src/index.js - MjButton CTA component with full attribute schema and padding/width calculation.
• mjml-carousel/src/index.js - Re-exports Carousel and CarouselImage for registration.
• mjml-carousel/src/Carousel.js - Master carousel component generating CSS radio-button interaction.
• mjml-carousel/src/CarouselImage.js - Individual carousel slide image component.
• mjml-cli/src/client.js - CLI entry, parses argv and delegates to command handlers.
• mjml-cli/src/commands/outputToConsole.js - Writes compiled HTML to stdout.
• mjml-core/ - Base BodyComponent class, mjml2html engine, context system, HTML attribute helpers.
• mjml-parser-xml/ - Converts raw MJML XML string into a structured AST consumed by mjml-core.
• mjml-preset-core/ - Aggregates all standard components and their allowed-children dependency map.
• mjml-validator/ - Exports dependencies map and assignDependencies; validates attribute types at compile time.

Common pitfalls and fixes

• ES module interop errors (__esModule / default import) — Set "esModuleInterop": true in tsconfig.json and use import mjml2html from 'mjml'; do not use require('mjml').default.
• static class fields syntax error in Node < 16 — Add @babel/plugin-proposal-class-properties or upgrade to Node 18+ which supports it natively.
• Missing component: Unknown component error — You forgot to call assignComponents / assignDependencies before invoking mjml2htmlCore directly; always use the top-level mjml package or replicate its bootstrap.
• htmlnano optional minify dependency absent — minify: true requires htmlnano and postcss to be installed separately (npm install htmlnano postcss); the error is silent in some versions.
• Browser build fails on fs / path imports — Use mjml-browser and its webpack config with the provided stubs; do not try to bundle mjml-core directly in a browser webpack target.
• validationLevel: 'strict' throws on unknown attributes — Third-party or custom components must be registered before compilation; use 'soft' during development to receive errors as an array rather than thrown exceptions.

Vibe-coding prompt template

I have purchased a source-available copy of the MJML email compiler monorepo.
The source is located in the `source/` directory of this project.
A detailed integration guide is in `source/USAGE.md`.
The upstream package name is `mjml` (npm: mjml).

Please help me integrate MJML into my existing Node.js/TypeScript project
step by step:

1. Read `source/USAGE.md` thoroughly before writing any code.
2. Install only the npm dependencies listed in the "Required dependencies"
   section — do NOT install `mjml` from npm; we are using the local source.
3. Configure Babel/TypeScript as described in "Project setup".
4. Create a `src/email/compiler.ts` module that exports a `compileEmail`
   function wrapping `mjml2html` from `source/mjml/src/index.js`.
5. Add an Express route `POST /api/send-email` that accepts a JSON body
   `{ to, mjmlSource }`, compiles the template, and logs the resulting HTML.
6. Show me any validation errors as structured JSON, not thrown exceptions.
7. Reference the real exports shown in USAGE.md — do not invent any APIs.
8. After each step, confirm which file you modified and what you changed.

License and credit

MJML is licensed under the MIT License. See source/LICENSE if present, or refer to the official repository for the full license text. Developed originally by Mailjet. Upstream package: mjml on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Nodemailer Node.js Email Sending Library

PHP, Laravel & Business Scripts

Free