The utility belt for MJML developers
Installing globally is the easiest way to get started, since you won't need any project-specific setup:
npm install -g mjml-utilsInstalling as a local dev-dependency gives you more flexibility:
npm install -D mjml-utilsIf 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.
The mju --build command compiles all MJML templates into HTML templates.
mju --build -i ./templates -o ./buildThe --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.
The mju --watch command will monitor all MJML templates in a specified directory and compile them to HTML every time they're modified.
mju --watch -i ./templates -o ./buildLike the --build command, the --watch command requires both input (-i) and output (-o) arguments.
The mju --send command sends compiled MJML templates as HTML emails to a recipient of your choosing using your Gmail credentials.
mju --send -o ./buildThe --send command will prompt you to provide all of the information needed to send test emails.
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-sendThis 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.
mjml-utils also has a built in helper method called inject. An example of its usage is below:
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.
To keep better organization of releases this project follows the Semantic Versioning 2.0.0 guidelines.
Want to contribute? Follow these recommendations.