Nodemailer MJML i18next Compiler

• Purpose: Nodemailer compile plugin that renders MJML templates with Handlebars and i18next translations.
• Why: Write responsive emails in MJML, keep copy in i18next JSON files, and inject dynamic data via Handlebars.

Install

• npm i nodemailer mjml i18next i18next-fs-backend handlebars
• Add this plugin as a dependency of your project (copy this folder or publish and npm i nodemailer-mjml-i18next-compiler).
• Install from npm: https://www.npmjs.com/package/nodemailer-mjml-i18next-compiler

Usage

const nodemailer = require('nodemailer');
const { mjmlI18nextCompiler } = require('nodemailer-mjml-i18next-compiler');

const transporter = nodemailer.createTransport({ /* SMTP config */ });

transporter.use('compile', mjmlI18nextCompiler({
  templatesDir: path.join(__dirname, 'templates'),
  partialsDir: path.join(__dirname, 'templates', 'partials'),
  localesDir: path.join(__dirname, 'locales'),
  defaultLocale: 'en',
  namespaces: ['common', 'emails'],
  defaultNamespace: 'common',
  mjmlOptions: { validationLevel: 'soft' },
  strict: false, // set true to error on MJML warnings
}));

await transporter.sendMail({
  from: '[email protected]',
  to: '[email protected]',
  template: 'welcome',           // resolves templates/welcome.mjml.hbs
  locale: 'en',
  context: { name: 'Taylor' },   // handlebars + i18next interpolation data
  // subject: 'Custom subject',
  // subjectKey: 'emails:welcome.subject',
});

Templates

• Place templates under templatesDir. The resolver tries in order:
  • <name>.mjml.hbs
  • <name>.hbs.mjml
  • <name>.mjml
  • <name>.hbs

Inside templates, you can use Handlebars and the t helper for translations:

<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text font-size="20px">{{t "emails:welcome.title" name=name}}</mj-text>
        <mj-text>{{t "common:greeting" name=name}}</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
  
</mjml>

i18next

• By default, the plugin initializes its own i18next instance with i18next-fs-backend and loads from locales/<lng>/<ns>.json.
• Provide your own initialized instance via i18next option to integrate with an existing i18next setup.
• In templates, {{t "key"}} and {{__ "key"}} are available. Locale is taken from mail.data.locale.

Options

• templatesDir: Absolute path to MJML/Handlebars templates. Required.
• partialsDir: Optional absolute path to Handlebars partials.
• localesDir: Absolute path to i18next locales folder. Default: locales.
• defaultLocale: Fallback language. Default: en.
• namespaces: i18next namespaces to use. Default: ["common"].
• defaultNamespace: Default i18next namespace. Default: "common".
• preload: Locales to preload. Default: [defaultLocale].
• mjmlOptions: Options passed to mjml().
• autoSubject: If no subject and translation exists at emails.<template>.subject, use it. Default: true.
• subjectNamespace: Namespace for auto-subject lookup (uses <subjectNamespace>:<template>.subject). Default: "emails".
• helpers: Object map of extra Handlebars helpers to register.
• force: Recompile even if mail.data.html already exists. Default: false.
• strict: Throw error when MJML reports errors. Default: false.

TypeScript

• Types are included via src/index.d.ts.
• Import styles:
  • CommonJS: const { mjmlI18nextCompiler } = require('nodemailer-mjml-i18next-compiler')
  • ESM/TS: import { mjmlI18nextCompiler } from 'nodemailer-mjml-i18next-compiler'
  • Options type: import type { MjmlI18nextOptions } from 'nodemailer-mjml-i18next-compiler'

Mail Data

• template: Template base name (without extension). Required if html is absent.
• context (or locals): Data for Handlebars and i18next interpolation.
• locale: Locale for translations (e.g., en, fr).
• subjectKey: Optional i18next key for subject. If missing and autoSubject is enabled, uses emails.<template>.subject if defined.

Example Project Layout

project/
  locales/
    en/
      common.json
      emails.json
  templates/
    welcome.mjml.hbs
    partials/
      footer.mjml.hbs

Notes

• The plugin compiles Handlebars first to produce MJML, then compiles MJML to HTML.
• You can access t/__ both as helpers and as functions in context.
• If you need plain-text generation, add it downstream (e.g., html-to-text).

Documentation

• GitHub Pages: https://xjodoin.github.io/nodemailer-mjml-i18next-compiler/
• Docs source: mkdocs.yml and docs/ in the repo.
• LLM context: https://xjodoin.github.io/nodemailer-mjml-i18next-compiler/llms.txt
• LLM full context: https://xjodoin.github.io/nodemailer-mjml-i18next-compiler/llms-full.txt

Contributors

• Primary author: Xavier Jodoin
• See all contributors: https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/graphs/contributors

License

• MIT — see LICENSE for details.