Security News
Combatting Alert Fatigue by Prioritizing Malicious Intent
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
a tool to build emails with cool stuff like mjml and different template engine like handlebars or eta.js
We know emails are VERY HARD
to develop from scratch.
Sometimes you can use tool like Maiject, SendPulse, MailerSend, Stripo.email etc. Some of this have cool interfaces with drag and drop and different actions to do.
So why you/your company should use this library?
This project wants to mix up MJML, a template engine for variables and a web server, to create a tool able to generate emails with a simple flow and one command. Please keep in mind that Maiject, SendPulse, MailerSend, Stripo.email etc maybe can be already perfect for your purpose.
npm i marilena
marilena provides a command witch generate a small but working example with eta.js, variables, layout and partials. You can choose to generate this example adding these commands to your package.json
and then run npm run generate-example
.
"type": "module",
"scripts": {
"start": "marilena --server --project example/marilena.config.mjs",
"build": "marilena --build --project example/marilena.config.mjs",
"generate-example": "marilena --create-example",
},
If you fails to generate the example or you want to build a project from 0 you need to crete marilena.config.mjs
file in the root of your project. Please check below the fields since any of these are required.
import path from "node:path";
// you can leverage your IDE's intellisense with jsdoc type hints
/** @type {import('../src/types').UserConfig} */
export default {
inputFolder: "./input",
outputFolder: "./output",
textVersion: (emailName, locale) => `${emailName}_text_version-${locale}.txt`,
htmlVersion: (emailName, locale) => `${emailName}-custom.html`,
locales: ["it", "en"],
templateOptions: {
engine: "eta",
prepareEngine: (eta) => {
eta.configure({
views: path.join(process.cwd(), "playground/input"),
});
},
},
mjmlParsingOptions: {
keepComments: false,
},
};
Edit you package.json
. By default marilena
try to find config in the root of your project. If you put the config in a different path, you need to pass --project
argument in the scripts
"scripts": {
"start": "marilena --server",
"build": "marilena --build",
},
create a file structures based on your config. Please remember that each email template requires index.html
as name, and variables are loaded only from variables.json
or variables.yml
. Yes you can use both :)
project
| marilena.config.mjs
│ package.json
│ input
│ └──common-en.json // common json variables for all en emails
│ └──common-it.yaml // common yaml variables for all it emails
│ └──buy // email name
││││││└─── index.html
││││││└─── en
│││││││││││└── variables.json // json variables for en buy email
││││││└─── it
│││││││││││└── variables.yaml // yaml variables for it buy email
3 - fill your emails template with MJML syntax
<mjml>
<mj-body>
<mj-section>
<mj-column>
<!-- eta js example, read below about template engine -->
<mj-text>hello <%= it.user %></mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
4 - run one of these 2 commands
# open a server on http://localhost:8080
npm run start
# build all emails based on config
npm run build
Under the hood a default configuration will be loaded but a file marilena.config.mjs
allow us to set:
name | required | description | default |
---|---|---|---|
inputFolder | folder where email are in the project. Path is relative to marilena.config.mjs | ./input | |
outputFolder | folder used for generated email (when run build command). Path is relative to marilena.config.mjs | ./output | |
locales | array of languages used. If you need only spanish email use an array of single value | ["es"] | |
templateOptions | if you chose to use one of supported engines, this part is mandatory to setup custom partial and other settings for the template engine selected. Read below for some use cases | empty | |
mjmlParsingOptions | options passed to mjml render. See: mjml options | ||
htmlVersion | function of type (emailName: string, locale: string) => string . If set, this function allow to customize the output html filename. The function must return file name es: ${emailName}-${locale}.html | index.html | |
textVersion | function of type (emailName: string, locale: string) => string . If set, this function allow to generate text version of email stripping all html. The function must return file name es: ${emailName}-${locale}-text-version.txt | ||
sendTestOptions | option in case you want to send the email to some account for testing. Setting this should add send-email button during development: Read below for some use cases |
Marilena uses dotenv
out of the box. So if you create .env
file (or it is created by runnning create-example
) marilena will load variables from there.
This project can producte output html from input template. But in a real word probably we store variables in some part and render some content multiple times (example a footer). In this case templateOptions
can define:
engine
: eta
or handlebars
are supported. These deps are peer-dependency so if you want to use ones please install that as dependency.prepareEngine
: define a callback where we can setup our engine. Basically you can define all things before the render. For example:templateOptions: {
engine: "eta",
prepareEngine: (eta) => {
// eta is an istance of new Eta() so you need to set at least views options for templates/layout/partials
eta.configure({
views: path.join(process.cwd(), "input"),
});
// we can call all eta-js api like:
eta.loadTemplate(...);
},
},
templateOptions: {
engine: "handlebars",
prepareEngine: (h) => {
// we can register partial like:
// handlebars is same of var h = require("handlebars");
h.registerPartial("myPartial", "partial with {{ user }}");
},
},
This option provides a fast way to test email sending an email to real account. You shoud pass also createTransport
function that return a Transporter
.
See nodemailer tutorial
Example marilena.config.mjs
to work with Aws SES:
import * as aws from "@aws-sdk/client-ses";
import nodemailer from "nodemailer";
export default {
...config,
sendTestOptions: {
to: "diego.tonini93@gmail.com",
from: "noreply@custom-domain.com", // this is not random email, but should be registered in you provider
createTransport: () =>
nodemailer.createTransport({
SES: {
ses: new aws.SES({
apiVersion: "2010-12-01",
region: "us-east-1",
credentials: {
accessKeyId: "...",
secretAccessKey: "...",
},
}),
aws,
},
}),
},
};
Example marilena.config.mjs
to work with forwardemail or other custom setting;
import nodemailer from "nodemailer";
export default {
...config,
sendTestOptions: {
to: "diego.tonini93@gmail.com",
from: "noreply@custom-domain.com", // this is not random email, but should be registered in you provider
createTransport: () =>
nodemailer.createTransport({
host: "smtp.forwardemail.net",
port: 465,
secure: true,
auth: {
// TODO: replace `user` and `pass` values from <https://forwardemail.net>
user: "REPLACE-WITH-YOUR-ALIAS@YOURDOMAIN.COM",
pass: "REPLACE-WITH-YOUR-GENERATED-PASSWORD",
},
}),
},
};
If you want to add a css file import in mj-include
tag. Path start from root directory of the project (like package json):
<mjml>
<mj-body>
<mj-include path="input/styles.css" type="css" css-inline="inline"/>
<!-- other mjml nodes -->
</mj-body>
</mjml>
FAQs
a tool to build emails with cool stuff like mjml and different template engine like handlebars or eta.js
The npm package marilena receives a total of 3 weekly downloads. As such, marilena popularity was classified as not popular.
We found that marilena demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.