mjml-utils
mjml-utils copied to clipboard
justinsisley
The utility belt for MJML developers
mjml-utils
The utility belt for MJML developers
Installation
Installing globally is the easiest way to get started, since you won't need any project-specific setup:
npm install -g mjml-utils
Installing as a local dev-dependency gives you more flexibility:
npm install -D mjml-utils
If you install mjml-utils locally, you'll probably want to configure it to run via your package.json scripts. This method is encouraged, and an example of local usage via package.json scripts is provided below.
Global Usage
--build
The mju --build command compiles all MJML templates into HTML templates.
mju --build -i ./templates -o ./build
The --build command requires input (-i) and output (-o) arguments. -i is the directory in which your raw MJML templates are located, and -o is the directory you would like the compiled HTML files written to.
With the optional extension (-e) argument you can specify the output file extension (default: .html) to your liking.
Note: only files with the
.mjmlfile extension will be compiled.
mju --build -i ./templates -o ./build -e .handlebars
--watch
The mju --watch command will monitor all MJML templates in a specified directory and compile them to HTML every time they're modified.
Note: only files with the
.mjmlfile extension will be compiled.
mju --watch -i ./templates -o ./build
Like the --build command, the --watch command requires both input (-i) and output (-o) arguments.
--send
The mju --send command sends compiled MJML templates as HTML emails to a recipient of your choosing using your Gmail credentials.
mju --send -o ./build
The --send command will prompt you to provide all of the information needed to send test emails.
NPM Script Usage
If you'd prefer to install mjml-utils locally, you can easily tailor its commands specifically for your project.
For example, if your project contains MJML email templates in the ./templates/email directory, and you'd like to compile them to the ./build/templates/email directory, you might configure your package.json file like this:
{
"name": "my-project",
"version": "1.0.0",
"scripts": {
"email-build": "mju --build -i ./templates/email -o ./build/templates/email",
"email-watch": "mju --watch -i ./templates/email -o ./build/templates/email",
"email-send": "mju --send -o ./build/templates/email"
},
"dependencies": {
"mjml": "*",
"mjml-utils": "*"
}
}
The above configuration would allow you to run the following commands from the command line:
npm run email-build
npm run email-watch
npm run email-send
This is the preferred way of using mjml-utils, since you can configure it on a per-project basis, and you won't have to remember any command line arguments other than the simple NPM script alias.
Module Usage
mjml-utils also has a few built-in helper functions.
inject()
Inject variables into your email templates.
Usage:
const mjmlUtils = require('mjml-utils');
const pathToHtmlEmailTemplate = path.join(__dirname, '../emails/welcome.html');
mjmlUtils.inject(pathToHtmlEmailTemplate, {
name: 'bob',
profileURL: 'https://app.com/bob',
})
.then(finalTemplate => {
// finalTemplate is an HTML string containing the template with all occurrences
// of `{name}` replaced with "bob", and all occurrences of `{profileURL}`
// replaced with "https://app.com/bob".
});
The above JavaScript assumes a template called welcome.html exists at the specified path, and that it's contents are something like the following example:
<html>
<body>
<h1>Welcome {name}</h1>
<p><a href="{profileURL}">Click here</a> to view your profile.</p>
</body>
</html>
This means your raw MJML template should contain the necessary template strings that you intend to replace with dynamic values.
sendmail()
Inject variables, compose, and send an email in one step. Caches templates in memory. Uses nodemailer to send email.
Usage (using nodemailer SES transport):
const mjmlUtils = require('mjml-utils');
const pathToHtmlEmailTemplate = path.join(__dirname, '../emails/welcome.html');
const accessKeyId = 'AWS_IAM_ACCESS_KEY_ID';
const secretAccessKey = 'AWS_IAM_SECRET_ACCESS_KEY';
const region = 'AWS_SES_REGION';
mjmlUtils.sendmail.config({
fromAddress: '[email protected]',
transport: nodemailer.createTransport(sesTransport({
accessKeyId,
secretAccessKey,
region,
})),
});
mjmlUtils.sendmail({
to: '[email protected]',
subject: 'Custom transactional email made easy!',
text: 'If the HTML email doesn\'t show up, this text should help you out.',
template: pathToHtmlEmailTemplate,
// The same data you would pass to #inject()
data: { confirmationURL: '...' }
})
.then(() => {
console.log('Email sent!');
})
.catch((error) => {
console.warn('mjmlUtils.sendmail error', error);
});
Versioning
To keep better organization of releases this project follows the Semantic Versioning 2.0.0 guidelines.
Contributing
Want to contribute? Follow these recommendations.
License
Credits
Icon by Flaticon
justinsisley