@molecule/api-templating-mjml

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

MJML email template provider for molecule.dev.

Implements the TemplateProvider interface using MJML for responsive email template rendering. Variable interpolation uses Handlebars syntax. Templates are first interpolated with data, then compiled from MJML to responsive HTML that works across all major email clients.

Quick Start

import { setProvider, render } from '@molecule/api-templating'
import { provider } from '@molecule/api-templating-mjml'

setProvider(provider)

const html = await render(
  `
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text>Hello {{name}}!</mj-text>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
`,
  { name: 'World' },
)

Type

provider

Installation

npm install @molecule/api-templating-mjml @molecule/api-templating handlebars mjml
npm install -D @types/mjml

API

Interfaces

MjmlTemplateConfig

Configuration options for the MJML template provider.

interface MjmlTemplateConfig {
  /**
   * Validation level for MJML templates.
   * - `'strict'` — `render()` throws on any MJML validation error
   * - `'soft'` — renders despite errors (default)
   * - `'skip'` — no validation at all
   *
   * Defaults to `'soft'`. Note: only `render()` enforces `'strict'` —
   * `renderCompiled()` never throws on MJML validation errors regardless
   * of this setting.
   */
  validationLevel?: MjmlValidationLevel

  /** Whether to minify the HTML output. Defaults to `false`. */
  minify?: boolean

  /** Whether to beautify the HTML output. Defaults to `false`. */
  beautify?: boolean

  /** File path for resolving `mj-include` relative paths. */
  filePath?: string

  /**
   * Built-in helpers to register on creation.
   * Keys are helper names, values are helper functions.
   */
  helpers?: Record<string, (...args: unknown[]) => string>

  /**
   * Built-in partials to register on creation.
   * Keys are partial names, values are partial template strings.
   */
  partials?: Record<string, string>
}

Types

MjmlValidationLevel

MJML validation level for template processing.

type MjmlValidationLevel = 'strict' | 'soft' | 'skip'

Functions

createProvider(config)

Creates an MJML template provider.

function createProvider(config?: MjmlTemplateConfig): TemplateProvider

• config — Provider configuration.

Returns: A TemplateProvider backed by MJML with Handlebars interpolation.

Constants

provider

The provider implementation with default configuration (soft validation).

const provider: TemplateProvider

Core Interface

Implements @molecule/api-templating interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-templating'
import { provider } from '@molecule/api-templating-mjml'

export function setupTemplatingMjml(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-templating ^1.0.1

Runtime Dependencies

• @molecule/api-templating

• handlebars

• mjml

• Validation defaults to 'soft' (render despite MJML errors). Set createProvider({ validationLevel: 'strict' }) to make render() throw on invalid MJML — but note renderCompiled() skips validation entirely.

• compile() pre-compiles only the Handlebars interpolation; the MJML → responsive-HTML conversion still runs on every renderCompiled() call.

• Raw (unescaped) interpolation is per-render only (options.escape: false on render()); compiled templates always escape.