Premail
An easy-to-use component-based build system for MJML, the email templating language, with Handlebars templating, Sass styles, and extra options.
Install / Use
/learn @premail/PremailREADME
MJML is a markup language for writing bulletproof HTML emails. It intentionally doesn't include a build process. This is that build process, and it's configurable to meet your needs and catch the edge cases.
Premail is component-based, and uses Handlebars for templating. Settings are defined in YAML configuration files, and theming happens in a design configuration file as well as (optionally) Sass files.
Email templates are all valid under MJML version 4.
One index.html file will be rendered, as well as (optionally) a plain-text
version, ready to import into your emailer of choice.
See an example of the default layout.
Read more at a quick introduction to Premail.
<!-- The following section, from "ts" to "te", is an automatically-generated table of contents, updated whenever this file changes. Do not edit within this section. --> <!-- prettier-ignore-start --> <!--ts--> <!-- Added by: runner, at: Tue Mar 22 01:10:46 UTC 2022 --> <!--te--> <!-- prettier-ignore-end -->
Features
-
MJMLv4-standard bulletproof code that will look its best across all email clients, reduced to the smallest possible size. CSS is inlined and HTML is minified as with all MJML, but we also add some extra checks, for instance, to make sure emojis are properly escaped and the file size doesn't hit Gmail's clipping limit.
-
Component-based templates that allow you to separate out things that don't often change (navigation menus, social media links, unsubscribe text) and things that will usually change (a header or banner, preheader text, and the main body of the email).
-
You can create multiple designs, and each time you create a new email you can choose from among your existing designs. This allows you to keep the structure of the design and the content of the email separate, and reduces errors.
-
As you're creating a design or crafting a new email, you can use a
watchtask to automatically recompile the result. -
Within each design, the CSS (created in Sass files) is automatically inlined in the HTML, thanks to MJML. Additionally, stub files exist for including pseudo-CSS styles (such as hover states) for email clients that support them, as well as styles specifically targeting Gmail.
-
A plain-text version of your email is optionally created, and Premail does a much better job than most email services at rendering it. While only a small number of your recipients will see the plain-text version, they are important for email deliverability. Within the plain-text version options, you can control whether certain elements like navigation or header/banner areas are included.
-
Configuration files are written in YAML, making them easy to read, and comments -- with links to relevant resources -- are included throughout.
-
Perfectly structured for including in a git repo -- don't rely on your email service provider to keep an archive of your past emails! And Prettier is included to automatically clean up template formatting for easier file-diffing.
When it comes to the content of your emails, optional enhancements can be controlled per-email:
- Transforming quotes, apostrophes, and dashes to their correct typographical versions; optical character alignment; and true small-caps formatting with Detergent and Typeset.
- Enforcing
proper image
alttags and making sure the supplied text doesn't break email code parsers. - Padding preview/preheader text to prevent things like navigation menu items from being visible in a recipient's inbox.
Feel free to make suggestions for more enhancements!
Custom MJML components
Premail also includes some MJML custom components for common use cases:
Setup and usage
Premail requires Node 12.x or 14.x to run. See the Premail setup documentation for details.
Installation
npm install -g premail
That's it! See setting up Premail for additional installation options.
Quickstart
- Install Premail (above).
- Create an emtpy directory and enter it on the command line.
- Run
premail init. This generates the Premail scaffolding and includes an example design and email source. - Run
premail build -e _example. This builds the example email. - Take a look at
emails/_example/distto see the built HTML and plain text versions of the email.
Head over to the Premail Usage Guide to start learning about how to use Premail with your own designs and emails.
CLI options
You can run premail -h to see the full list of options:
Usage: premail <command> [options]
Commands:
premail new <email|design> <dest> Create a new email or design in <dest>
premail build Build an email
premail watch Watch design and configuration files and
rebuild as necessary
premail clean Remove generated files from the current
design or email
premail paths List paths being used with the current
configuration and command-line flags
premail format Format templates with Prettier
premail init Initialize a Premail project
premail destroy Destroy this Premail project
Email development:
-d, --design Specify design di
