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.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

PHP, Laravel & Business Scripts

무료