Email Templating

Email templating module

Install: @travetto/email-template

npm install @travetto/email-template

# or

yarn add @travetto/email-template

This is primarily a set of command line tools for compiling and developing templates. The inputs are compiled files, generally under the support/ folder, that represents the necessary input for the email compilation. Email Inky Templates shows this pattern by leveraging JSX bindings for the inky framework, allowing for compile-time checked templates.

Asset Management

The templating process involves loading various assets (html, css, images), and so there is provision for asset management and loading. The templating config allows for specifying asset paths, with the following paths (in order of precedence):

%ROOT%/resources/email
@travetto/email-{engine}/resources/email When looking up a resources, every asset folder is consulted, in order, and the first to resolve an asset wins. This allows for overriding of default templating resources, as needed. The compilation process will convert .email.html files into .compiled.html, .compiled.text and .compiled.subject suffixes to generate the outputs respectively.

Template Extension

The template extension points are defined at:

email/main.scss - The entry point for adding, and overriding any sass
email/{engine}.wrapper.html - The html wrapper for the specific templating engine implementation.

Template Compilation

The general process is as follows:

Load in the email template.
Resolve any associated stylings for said template.
Render template into html, text, and subject outputs.
Inline and optimize all images for html email transmission.

Images

When referencing an image from the resources folder in a template, e.g.

Code: Sample Image Reference

<img src="/email/logo.png">

The image will be extracted out and embedded in the email as a multi part message. This allows for compression and optimization of images as well as externalizing resources that may not be immediately public. The currently supported set of image types are:

jpeg
png

Template Development

The module provides Command Line Interface and VSCode plugin support for email template development.

CLI Compilation

The module provides Command Line Interface support for email template compilation also. Running

Terminal: Running template compilation

$ trv email:compile -h

Usage: email:compile [options]

Options:
  -w, --watch            Compile in watch mode
  -m, --module <string>  Module to run for
  -h, --help             display help for command

Will convert all .email.html files into the appropriate .compiled.html, .compiled.text and .compiled.subject files. These will be used during the running of the application. By default these files are added to the .gitignore as they are generally not intended to be saved but to be generated during the build process.

VSCode Plugin

In addition to command line tools, the VSCode plugin also supports:

automatic compilation on change
real-time rendering of changes visually
ability to send test emails during development
ability to define custom context for template rendering

@travetto/email-template

Email Templating