swig-email-templates

This package is unmaintained; please volunteer if you want it to not rely on outdated dependencies.

swig-email-templates is a Node.js module for rendering emails with Swig templates and email-friendly inline CSS using juice, inspired by niftylettuce/node-email-templates.

Features

• Uses swig, which supports Django-inspired template inheritance.
• Uses juice, which takes an HTML file and inlines all the <link rel="stylesheet">s and the <style>s.
• URL rewrite support - you can provide a function to rewrite your links.
• Text emails - for a template name passed into render(), if a file exists with the same name but a .txt extension it will be rendered separately. If the .txt file does not exist, html-to-text will auto-generate a text version of the html file. This can be disabled with the option text: false.

Upgrading from 1.x

Check out the changelog for details of what changed since 1.x. The upgrade should be pretty straightforward.

Quick start

Install:

npm install swig-email-templates

A quick working example:

var EmailTemplates = require('swig-email-templates');
var nodemailer = require('nodemailer');
var transporter = nodemailer.createTransport();

var templates = new EmailTemplates();
var context = {
  meatballCount: 9001
};

const { html, text, subject } = await templates.render('meatball-sandwich.html', context) 
transporter.sendMail({
    from: 'sender@address',
    to: 'receiver@address',
    subject: subject,
    html: html,
    text: text
});

EmailTemplates API

Constructor(options)

Creates a a new EmailTemplates instance.

var EmailTemplates = require('swig-email-templates');
var templates = new EmailTemplates();

To set options, pass an object to the constructor. It can have the following keys:

root (string)

Path to template files. Defaults to path.join(__dirname, 'templates')

swig (object)

Swig options. Gets passed to swig.setDefaults(). See swig documentation for more information.

filters (object)

An object of Swig filters to set. Format: { name1: method1, name2: method2 }. For more information see Swig documentation for setFilter().

juice (object)

Juice options. See juice documentation for more information.

rewrite (function(cheerio instance))

After rendering the template and running the rewriteUrl function (see below), but before inlining resources, this function will be called if provided. It will be passed a cheerio instance and can alter its content. Cheerio instances are modified in-place so it does not need to return a value.

rewriteUrl (function (string) => string)

Each a href attribute in the output HTML will have its value replaced by the result of calling this function with the original href value.

text (boolean)

Whether to generate text alternative to HTML. Defaults to true.

Example

new EmailTemplates({
  root: '/var/www/test.site/templates',
  text: false,       // Disable text alternatives
  swig: {
    cache: false     // Don't cache swig templates
  },
  filters: {
    upper: function(str) {
      return str.toUpperCase();
    }
  },
  juice: {
    webResources: {
      images: 8      // Inline images under 8kB
    }
  },
  rewriteUrl: function (url) {
    return url + 'appendage';
  },
  rewrite: function($) {
    $("img").each(function(idx, anchor) {
      $(anchor).attr('src', 'no-img.png');
    });
  }
})

render(templateName, context, callback?)

Render a template with templateName, with the context provided.

If no callback is given, returns a promise which resolves to an object that looks like { html, text, subject }.

If a callback function is given, use legacy callback style. The callback has the signature function(err, html, text, subject).

Example (promise):

const EmailTemplates = require('swig-email-templates');
const templates = new EmailTemplates();
const { html, text, subject } = await templates.render('template.html', { user: 55 })
// html is inlined html
// text is text equivalent
// subject is parsed subject template or null if not found

Example (callback):

const EmailTemplates = require('swig-email-templates');
const templates = new EmailTemplates();
templates.render('template.html', { user: 55 }, function (err, html, text, subject) {
  // html is inlined html
  // text is text equivalent
  // subject is parsed subject template or null if not found
})

Behaviour of text templates

If the 'text' option is true (see above), then swig-email-templates will attempt to create a text equivalent as well as your HTML. By default, this will be by rendering the HTML output as text using html-to-text.

You can provide your own text template to override this behaviour. This should have the same basename as your HTML template but end in '.txt' instead of '.html'. For example, if your HTML template is 'template.html' then the text version should be 'template.txt'. This will receive the same context as the HTML template.

If the 'text' option is false, then no text alternative will be generated and the callback passed to the EmailTemplate.render() function will receive a falsy value instead of text as its third argument.

Behaviour of subject templates

swig-email-templates will attempt to create a text equivalent as well as your HTML. This template should have the same basename as your HTML template but end in .subject.txt. This will receive the same context as the HTML template.

Using subject templates, you can generate subject that contains variables.

Command Line

Installing swig-email-templates through npm will put the swig-email-templates command in your system path, allowing it to be run from any directory.

Usage

swig-email-templates [files] [options]

Where [files] can be any number of input files to process.

The options are:

• -v, --version: Display the installed version of swig-email-templates
• -h, --help: Show the help screen
• -o, --output: The directory to output your files to. Defaults to stdout
• -r, --root: The root location for the files. The default is ..
• -j, --json: The file that contains your context, stored in JSON.
• -c, --context: The file that contains your context, stored as a CommonJS module. Used only if -j is not provided.

Example

The following example renders two files, email1.html and email2.html, which are both contained in the cwd. It uses the context stored in context/main.json for rendering, and places the results in the folder output.

swig-email-templates email1.html email2.html -o output/ -j context/main.json

Tests

npm test