Email Compilation Support

Email compiling module

Install: @travetto/email-compiler

npm install @travetto/email-compiler

# or

yarn add @travetto/email-compiler

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):

1. %ROOT%/resources/email
2. @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:

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

Template Compilation

The general process is as follows:

1. Load in the email template.
2. Resolve any associated stylings for said template.
3. Optimize styles against provided html, removing all unused stylings
4. Render template into html, text, and subject outputs.
5. 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
  -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