node package manager

swig-email-templates

Node.js module for rendering emails with swig templates and email-friendly inline CSS

swig-email-templates

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.

  • 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.

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

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
};
 
templates.render('meatball-sandwich.html', context, function(errhtmltext) {
 
  // Send email 
  transporter.sendMail({
      from: 'sender@address',
      to: 'receiver@address',
      subject: 'Meatball delivery',
      html: html,
      text: text
  });
 
});

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:

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

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

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

Juice options. See juice documentation for more inforation.

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.

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.

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

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

Render a template with templateName, with the context provided. Callback takes three parameters: (error, html, text).

Example:

var EmailTemplates = require('swig-email-templates');
var templates = new EmailTemplates();
templates.render('template.html', { user: 55 }, function (errhtmltext) {
  // html is inlined html 
  // text is text equivalent 
})

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.

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.

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.

The following examples 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 render email1.html email2.html -o output/ -j context/main.json
npm test