{"id":19610622,"url":"https://github.com/justinsisley/mjml-utils","last_synced_at":"2025-05-11T15:43:18.289Z","repository":{"id":57298714,"uuid":"52644722","full_name":"justinsisley/mjml-utils","owner":"justinsisley","description":"The utility belt for MJML developers","archived":false,"fork":false,"pushed_at":"2018-03-27T04:39:56.000Z","size":37,"stargazers_count":110,"open_issues_count":4,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-23T00:19:08.006Z","etag":null,"topics":["email","email-boilerplate","email-campaigns","mjml","nodejs","responsive-email"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justinsisley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-27T01:54:48.000Z","updated_at":"2025-04-02T19:05:43.000Z","dependencies_parsed_at":"2022-08-26T18:02:34.469Z","dependency_job_id":null,"html_url":"https://github.com/justinsisley/mjml-utils","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinsisley%2Fmjml-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinsisley%2Fmjml-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinsisley%2Fmjml-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinsisley%2Fmjml-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinsisley","download_url":"https://codeload.github.com/justinsisley/mjml-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253432485,"owners_count":21907760,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","email-boilerplate","email-campaigns","mjml","nodejs","responsive-email"],"created_at":"2024-11-11T10:31:11.000Z","updated_at":"2025-05-10T14:43:55.638Z","avatar_url":"https://github.com/justinsisley.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"mjml-utils\" src=\"https://image.flaticon.com/icons/svg/134/134963.svg\" width=\"144\"\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\n  mjml-utils\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  The utility belt for \u003ca href=\"https://mjml.io/\"\u003eMJML\u003c/a\u003e developers\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/mjml-utils\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/mjml-utils.svg?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/mjml-utils\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/mjml-utils.svg?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/justinsisley/mjml-utils/blob/master/LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/licence-MIT-blue.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[Changelog](https://github.com/justinsisley/mjml-utils/releases)\n\n## Installation\n\nInstalling globally is the easiest way to get started, since you won't need any project-specific setup:\n\n```bash\nnpm install -g mjml-utils\n```\n\nInstalling as a local dev-dependency gives you more flexibility:\n\n```bash\nnpm install -D mjml-utils\n```\n\nIf 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](#npm-script-usage).\n\n## Global Usage\n\n#### --build\n\nThe `mju --build` command compiles all MJML templates into HTML templates.\n\n```bash\nmju --build -i ./templates -o ./build\n```\n\nThe `--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.\nWith the optional extension (`-e`) argument you can specify the output file extension (default: `.html`) to your liking.\n\n\u003e Note: only files with the `.mjml` file extension will be compiled.\n\n```bash\nmju --build -i ./templates -o ./build -e .handlebars\n```\n\n#### --watch\n\nThe `mju --watch` command will monitor all MJML templates in a specified directory and compile them to HTML every time they're modified.\n\n\u003e Note: only files with the `.mjml` file extension will be compiled.\n\n```bash\nmju --watch -i ./templates -o ./build\n```\n\nLike the `--build` command, the `--watch` command requires both input (`-i`) and output (`-o`) arguments.\n\n#### --send\n\nThe `mju --send` command sends compiled MJML templates as HTML emails to a recipient of your choosing using your Gmail credentials.\n\n```bash\nmju --send -o ./build\n```\n\nThe `--send` command will prompt you to provide all of the information needed to send test emails.\n\n## NPM Script Usage\n\nIf you'd prefer to install __mjml-utils__ locally, you can easily tailor its commands specifically for your project.\n\nFor 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:\n\n```json\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"email-build\": \"mju --build -i ./templates/email -o ./build/templates/email\",\n    \"email-watch\": \"mju --watch -i ./templates/email -o ./build/templates/email\",\n    \"email-send\": \"mju --send -o ./build/templates/email\"\n  },\n  \"dependencies\": {\n    \"mjml\": \"*\",\n    \"mjml-utils\": \"*\"\n  }\n}\n```\n\nThe above configuration would allow you to run the following commands from the command line:\n\n```bash\nnpm run email-build\nnpm run email-watch\nnpm run email-send\n```\n\nThis 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.\n\n## Module Usage\n\n__mjml-utils__ also has a few built-in helper functions.\n\n#### inject()\n\nInject variables into your email templates.\n\nUsage:\n\n```javascript\nconst mjmlUtils = require('mjml-utils');\nconst pathToHtmlEmailTemplate = path.join(__dirname, '../emails/welcome.html');\n\nmjmlUtils.inject(pathToHtmlEmailTemplate, {\n  name: 'bob',\n  profileURL: 'https://app.com/bob',\n})\n.then(finalTemplate =\u003e {\n  // finalTemplate is an HTML string containing the template with all occurrences\n  // of `{name}` replaced with \"bob\", and all occurrences of `{profileURL}`\n  // replaced with \"https://app.com/bob\".\n});\n```\n\nThe above JavaScript assumes a template called `welcome.html` exists at the specified path, and that it's contents are something like the following example:\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eWelcome {name}\u003c/h1\u003e\n\n    \u003cp\u003e\u003ca href=\"{profileURL}\"\u003eClick here\u003c/a\u003e to view your profile.\u003c/p\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThis means your raw MJML template should contain the necessary template strings that you intend to replace with dynamic values.\n\n#### sendmail()\n\nInject variables, compose, and send an email in one step. Caches templates in memory. Uses [nodemailer](https://github.com/nodemailer/nodemailer) to send email.\n\nUsage (using nodemailer SES transport):\n\n```javascript\nconst mjmlUtils = require('mjml-utils');\nconst pathToHtmlEmailTemplate = path.join(__dirname, '../emails/welcome.html');\nconst accessKeyId = 'AWS_IAM_ACCESS_KEY_ID';\nconst secretAccessKey = 'AWS_IAM_SECRET_ACCESS_KEY';\nconst region = 'AWS_SES_REGION';\n\nmjmlUtils.sendmail.config({\n  fromAddress: 'you@domain.com',\n  transport: nodemailer.createTransport(sesTransport({\n    accessKeyId,\n    secretAccessKey,\n    region,\n  })),\n});\n\nmjmlUtils.sendmail({\n  to: 'someone@domain.com',\n  subject: 'Custom transactional email made easy!',\n  text: 'If the HTML email doesn\\'t show up, this text should help you out.',\n  template: pathToHtmlEmailTemplate,\n  // The same data you would pass to #inject()\n  data: { confirmationURL: '...' }\n})\n.then(() =\u003e {\n  console.log('Email sent!');\n})\n.catch((error) =\u003e {\n  console.warn('mjmlUtils.sendmail error', error);\n});\n```\n\n## Versioning\n\nTo keep better organization of releases this project follows the [Semantic Versioning 2.0.0](http://semver.org/) guidelines.\n\n## Contributing\nWant to contribute? [Follow these recommendations](https://github.com/justinsisley/mjml-utils/blob/master/CONTRIBUTING.md).\n\n## License\n[MIT License](https://github.com/justinsisley/mjml-utils/blob/master/LICENSE.md) © [Justin Sisley](http://justinsisley.com/)\n\n## Credits\nIcon by [Flaticon](http://www.flaticon.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinsisley%2Fmjml-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinsisley%2Fmjml-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinsisley%2Fmjml-utils/lists"}