xjodoin.github.io

# Nodemailer MJML i18next Compiler

> Nodemailer compile plugin that renders MJML templates with Handlebars and i18next translations to produce responsive HTML emails from MJML.

This file points LLMs to concise, high-signal references for using the library. Core flow: Handlebars renders data and translations into MJML; MJML compiles to responsive HTML; the Nodemailer compile plugin assigns the result to `mail.data.html` and resolves a translated subject when configured. Templates are resolved by trying `<name>.mjml.hbs`, `.hbs.mjml`, `.mjml`, then `.hbs`. i18n defaults to filesystem-backed `i18next` loading from `locales/<lng>/<ns>.json`. Use `{{t "ns:key"}}` or `{{__ "ns:key"}}` in templates; locale comes from `mail.data.locale`.

Important notes:

- The plugin runs in Nodemailer’s compile phase (`transporter.use('compile', ...)`).
- `strict` throws on MJML errors; otherwise errors are exposed at `mail.data.mjmlErrors`.
- Subjects: set `mail.data.subject`, or use `mail.data.subjectKey`, or enable `autoSubject` (default) to use `<subjectNamespace>:<template>.subject`.
- Security: avoid untrusted helpers/partials; pin `templatesDir`, `partialsDir`, and `localesDir` paths.

## Docs

- [Overview](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/docs/index.md): What the plugin does and a quick start.
- [Usage](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/docs/usage.md): Templates, helpers, i18n, and mail data fields.
- [Options](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/docs/options.md): Full `mjmlI18nextCompiler` configuration.
- [Changelog (docs)](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/docs/changelog.md): Release notes on the docs site.

## API & Source

- [Runtime entry (`src/index.js`)](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/src/index.js): Compiler implementation, template resolution, helpers, and subject logic.
- [Types (`src/index.d.ts`)](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/src/index.d.ts): TypeScript declarations including `MjmlI18nextOptions`.

## Getting Started

- [README](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/README.md): Install, usage example, template format, and notes.
- [Example sender (`example/send.js`)](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/example/send.js): Minimal demo using the plugin.

## Example Assets

- [Template: `welcome.mjml.hbs`](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/example/templates/welcome.mjml.hbs): Example MJML + Handlebars template.
- [Partial: `partials/footer.mjml.hbs`](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/example/templates/partials/footer.mjml.hbs): Example Handlebars partial.
- [Locales: `en/emails.json`](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/example/locales/en/emails.json): Subject/title strings.
- [Locales: `en/common.json`](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/example/locales/en/common.json): Shared strings.

## Scripts

- [Smoke test (`scripts/smoke.js`)](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/scripts/smoke.js): Basic compile + subject validation against the example.

## Project Metadata

- [CHANGELOG.md](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/CHANGELOG.md): Versioned changes.
- [LICENSE](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/LICENSE): MIT license.
- [AUTHORS](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/AUTHORS): Project authors.
- [mkdocs.yml](https://github.com/xjodoin/nodemailer-mjml-i18next-compiler/blob/main/mkdocs.yml): Docs site configuration.

## Optional

- [Nodemailer plugin docs](https://nodemailer.com/usage/plugins/): How compile plugins integrate in Nodemailer.
- [MJML documentation](https://documentation.mjml.io/): MJML components and options.
- [Handlebars guide](https://handlebarsjs.com/guide/): Templates, helpers, and partials.
- [i18next core](https://www.i18next.com/): i18n concepts and usage.
- [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend): Filesystem backend used when no custom i18next instance is provided.