Handlebars Email Templates for Node.js

Handlebars is the most common templating layer in Node.js email stacks because it is logic-less by design: the template can iterate, branch, and substitute, but it cannot run arbitrary JavaScript. For transactional mail — password resets, receipts, shipping alerts — that constraint is a feature. The render is deterministic, the attack surface is small, and the output is plain HTML that you can hand to a CSS inliner before SMTP dispatch. This guide covers the project layout, partial and helper registration, precompilation, the compile-inline-send pipeline, and the escaping rules that keep dynamic data from breaking your markup.

Why Handlebars Dominates Node ESP Stacks

Most Node-based email services start with Handlebars for three reasons. First, it is logic-less, so template authors (often designers or marketing engineers) cannot accidentally embed business logic or block the event loop. Second, it has first-class partials — reusable fragments like a header, footer, or button — that compose cleanly into layouts. Third, it has helpers: small registered functions for formatting currency, dates, or conditional blocks, which keep formatting concerns out of the calling code.

The trade-off is that Handlebars does not produce email-safe HTML on its own. It substitutes values into whatever markup you write, and it does not inline CSS. Email clients ignore most <style> blocks and external stylesheets, so the rendered HTML must run through a CSS inliner pipeline before sending. The correct order is always compile (Handlebars produces HTML) → inline (move CSS to style attributes) → send. Inlining before interpolation, or sending un-inlined output, is the single most common failure in these stacks.

If you are evaluating other engines, the Jinja2 for Python apps guide covers the equivalent server-side approach, and MJML component architecture covers a higher-level abstraction that emits table-driven HTML for you.

The Handlebars build path: partials and helpers feed a compile step, the inliner runs on final markup, and escaping mode decides whether dynamic data is safe.

Project Layout: Layouts, Partials, and Helpers

A maintainable Handlebars email project separates concerns into three directories. Layouts hold the page shell, partials hold reusable fragments, and helpers hold formatting functions. The render module wires them together once at boot.

emails/
├── layouts/
│   └── base.hbs            # <!DOCTYPE>, <head>, outer table wrapper, {{> body}}
├── partials/
│   ├── header.hbs          # logo row
│   ├── footer.hbs          # legal text + unsubscribe
│   └── button.hbs          # bulletproof CTA fragment
├── templates/
│   ├── password-reset.hbs
│   └── receipt.hbs
└── render.js               # registers partials + helpers, exports render()

Keep templates flat and let partials carry the shared chrome. The header, footer, and button render identically across every transactional message, so they live in partials/ and are registered once.

Core Implementation: Render Function with Partials, Helpers, and Inliner

This is the complete render path. It registers every partial and helper at module load, compiles the requested template against a layout, then runs the output through Juice. Registration happens once — not per send — so the compiled partial cache is reused across the process lifetime.

// render.js — Handlebars render() feeding a CSS inliner. Node 18+, handlebars ^4.7, juice ^11.
const fs = require('fs');
const path = require('path');
const Handlebars = require('handlebars');
const juice = require('juice');

const PARTIALS_DIR = path.join(__dirname, 'partials');
const TEMPLATES_DIR = path.join(__dirname, 'templates');
const LAYOUT = fs.readFileSync(path.join(__dirname, 'layouts', 'base.hbs'), 'utf8');

// --- Register partials once: header, footer, button reused across every message ---
for (const file of fs.readdirSync(PARTIALS_DIR)) {
  const name = path.basename(file, '.hbs');               // "header", "footer", "button"
  const src = fs.readFileSync(path.join(PARTIALS_DIR, file), 'utf8');
  Handlebars.registerPartial(name, src);                  // referenced as {{> header}}
}

// --- Custom helpers: formatting concerns stay out of business code ---
Handlebars.registerHelper('formatCurrency', (cents, currency = 'USD') => {
  // Intl runs at render time on the server (Node), NOT in the email client.
  const value = (Number(cents) || 0) / 100;
  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(value);
});

Handlebars.registerHelper('formatDate', (iso, locale = 'en-US') => {
  // Render to a fixed string — email clients have no JS/Intl, so format server-side.
  return new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(new Date(iso));
});

// Block helper for conditional rows — logic-less templates cannot do `>` inline.
Handlebars.registerHelper('gt', function (a, b, options) {
  return a > b ? options.fn(this) : options.inverse(this);
});

// Compile the layout once; it wraps body content via {{{body}}} (triple-stache: see escaping below).
const layoutTemplate = Handlebars.compile(LAYOUT);
const templateCache = new Map();

function getTemplate(name) {
  if (!templateCache.has(name)) {
    const src = fs.readFileSync(path.join(TEMPLATES_DIR, `${name}.hbs`), 'utf8');
    templateCache.set(name, Handlebars.compile(src));     // cache compiled AST per template
  }
  return templateCache.get(name);
}

/**
 * render() — compile → inline → return. Inlining runs on FINAL markup only.
 */
function render(templateName, context) {
  const body = getTemplate(templateName)(context);        // 1. interpolate template
  const fullHtml = layoutTemplate({ ...context, body });  // 2. wrap in <head>/<style> layout
  // 3. inline AFTER interpolation so Juice sees the real CSS + real markup.
  //    Gmail/Yahoo strip <head><style>; inlining moves rules to style="" attributes.
  return juice(fullHtml, { preserveMediaQueries: true }); // keep @media for iOS Mail / Apple Mail
}

module.exports = { render };

The preserveMediaQueries: true option matters: Juice would otherwise strip the @media rules that iOS Mail and Apple Mail rely on for responsive resizing. For the deeper inliner configuration — including how to keep MSO conditional comments intact — see the inline CSS automation reference.

Second Pattern: Layout + Partials Structure

The layout file is a plain .hbs shell. It pulls in the header and footer partials and exposes a {{{body}}} slot for the per-message content. Note the triple-stache on body — the body is already-rendered, trusted HTML, so it must not be re-escaped.

{{!-- layouts/base.hbs --}}
<!DOCTYPE html>
<html lang="{{lang}}" xmlns:v="urn:schemas-microsoft-com:vml">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <style>
    /* Juice inlines these; @media survives for iOS Mail / Apple Mail */
    .container { width: 600px; }
    @media only screen and (max-width: 600px) { .container { width: 100% !important; } }
  </style>
</head>
<body style="margin:0;padding:0;background:#f4f4f5;">
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
    <tr><td align="center">
      <table role="presentation" class="container" cellpadding="0" cellspacing="0">
        {{> header}}
        {{{body}}}  {{!-- triple-stache: body is pre-rendered HTML, do not escape --}}
        {{> footer logoUrl=logoUrl year=year}}
      </table>
    </td></tr>
  </table>
</body>
</html>

{{!-- partials/button.hbs — passed label + url by the calling template --}}
{{!-- Outlook 2016-2021 (Word engine) ignores padding on <a>; use a table cell button --}}
<table role="presentation" cellpadding="0" cellspacing="0" align="center">
  <tr><td bgcolor="#A53860" style="border-radius:6px;">
    <a href="{{url}}" style="display:inline-block;padding:14px 28px;color:#ffffff;
       font-family:Arial,sans-serif;font-size:16px;text-decoration:none;">{{label}}</a>
  </td></tr>
</table>

{{!-- templates/receipt.hbs --}}
{{> button label="View receipt" url=receiptUrl}}
<table role="presentation" width="100%">
  {{#each items}}
  <tr>
    <td style="font-family:Arial,sans-serif;font-size:14px;">{{this.name}}</td>
    {{!-- helper output is a SafeString from Intl; double-stache still renders it correctly --}}
    <td align="right" style="font-family:Arial,sans-serif;font-size:14px;">{{formatCurrency this.cents}}</td>
  </tr>
  {{/each}}
</table>
<p style="font-family:Arial,sans-serif;font-size:14px;">Charged on {{formatDate chargedAt}}.</p>

Precompilation for Performance

In a high-throughput sender, compiling templates on every request wastes CPU. Two options reduce that cost. The runtime cache shown above (templateCache) compiles each template once per process. For serverless or edge runtimes where cold starts dominate, precompile templates at build time with the handlebars CLI and ship the compiled functions, loading only handlebars/runtime at request time.

# Precompile at build time — ships JS functions, not source. Smaller runtime, no parse cost.
npx handlebars templates/ partials/ -f dist/templates.js
# At runtime require('handlebars/runtime') only — the full compiler is not bundled.

Escaping and XSS: The Triple-Stache Danger

Handlebars HTML-escapes {{double-stache}} output by default — <, >, &, ", and ' become entities. This is what protects you when a user sets their display name to <script> or a product title contains an ampersand. The {{{triple-stache}}} form emits raw, unescaped HTML and bypasses that protection entirely.

{{name}}      {{!-- escaped: "A & B" → "A &amp; B" — SAFE for any user-supplied value --}}
{{{rawHtml}}} {{!-- raw: emits markup verbatim — XSS if rawHtml is attacker-controlled --}}

Only ever use triple-stache for HTML you generated and sanitized yourself, such as the pre-rendered {{{body}}} slot in the layout. Never feed user input through triple-stache. If you must allow rich text, sanitize it server-side (for example with sanitize-html) before it reaches the template.

Internationalization

Because helpers run on the server, localization belongs there too. Pass a lang into the context, resolve translated strings in a t helper, and let formatDate/formatCurrency take a locale argument. The email client never runs Intl, so every locale-dependent string must be a fixed string by the time it leaves render().

const messages = require('./i18n');  // { en: {...}, de: {...}, ja: {...} }
Handlebars.registerHelper('t', (key, options) => {
  const lang = options.data.root.lang || 'en';
  return messages[lang]?.[key] ?? messages.en[key] ?? key;  // fall back to English, then key
});

Provider and Client Constraint Table

The templating engine is invisible to the recipient — what matters is the rendered HTML it produces. These constraints apply to the output of the compile-inline-send pipeline, not to Handlebars syntax.

Constraint on rendered output	Why it matters	Affected clients
`<head><style>` is stripped or ignored	Must inline CSS post-render	Gmail (web/app), Yahoo, Samsung Email
`@media` queries must survive inlining	Responsive resize breaks otherwise	iOS Mail, Apple Mail
Padding on `<a>` ignored; needs table-cell button	Buttons collapse to text size	Outlook 2016/2019/365 (Word engine)
VML required for rounded/background buttons	CSS radius dropped	Outlook 2016/2019/365
Entity-escaped data renders literally	Unescaped `<` breaks layout	Gmail, Apple Mail, Samsung Email
102KB message clipping	Strip whitespace in render	Gmail (web/app)

Numbered Pipeline Integration Steps

Register once. At process boot, call registerPartial for every file in partials/ and registerHelper for each formatting function. Never register inside the per-request path.
Compile and cache. Compile each layout and template to its AST on first use; store the compiled function in a Map. In serverless, precompile at build time instead.
Interpolate. Call the compiled template with the request context to produce raw HTML. All Intl/i18n resolution happens here, server-side.
Inline. Run the raw HTML through Juice with preserveMediaQueries: true. This is step 4, never earlier — the inliner must see the final markup.
Validate. Assert the output contains role="presentation" tables and no leftover {{ braces (a sign of an unrendered variable).
Dispatch. Hand the inlined HTML to the ESP (SES SendRawEmail, Postmark, SendGrid). Compilation must finish before any network call.

Debugging

Partial not found — Error: The partial X could not be found. The partial was never registered, or the name passed to {{> X}} does not match the registered name (registration uses the filename without extension). Confirm registerPartial ran before the first render() and that the casing matches.

Helper undefined / renders as missing — Missing helper: "formatCurrency". The helper was registered after the template compiled, or in a different Handlebars instance than the one compiling. Register all helpers at module load, and make sure only one handlebars copy is installed (npm ls handlebars).

HTML-escaped markup showing as literal text — you see <b>Hi</b> in the inbox. You passed HTML through a double-stache. Switch to triple-stache only if the value is trusted and sanitized; otherwise the data should stay escaped and you should restructure the template to use real tags.

Inliner running before interpolation — buttons unstyled, style attributes missing dynamic values. Juice was called on the template source, not the rendered output. Inlining must be the last step, after interpolation, as in render() above.

Leftover {{ }} in the inbox — a variable name was misspelled or absent from the context. Enable strict mode (Handlebars.compile(src, { strict: true })) in staging to throw on missing variables instead of rendering empty.

Partial Context: Parameters, `@root`, `@index`, and Block Params

A partial does not automatically see the whole render context. By default {{> footer}} inherits the current scope, but the moment you are inside an {{#each}} the current scope is the loop item — so a footer that needs the top-level year will find it missing. Three mechanisms solve this: explicit partial parameters, the @root data variable, and @index/block params for loop position.

{{!-- templates/digest.hbs — explicit params + @root + @index --}}
<table role="presentation" width="100%">
  {{#each notifications}}
    {{!-- pass scoped data explicitly so the partial does not depend on loop scope --}}
    {{> row label=this.title position=@index logoUrl=@root.logoUrl}}
  {{/each}}
</table>
{{!-- @root reaches the top-level context even from inside the loop above --}}
{{> footer year=@root.year unsubscribeUrl=@root.unsubscribeUrl}}

{{!-- partials/row.hbs — receives label, position, logoUrl as named params --}}
{{!-- Outlook 2016/2019/365 (Word engine) needs explicit width on the td, not %  --}}
<tr>
  <td width="40" style="font-family:Arial,sans-serif;font-size:14px;">{{position}}.</td>
  <td style="font-family:Arial,sans-serif;font-size:14px;">{{label}}</td>
</tr>

Block params ({{#each items as |item idx|}}) name the loop variable and index without relying on the implicit this/@index, which keeps nested loops readable — the inner loop no longer shadows the outer item. For a header that must resize on phones, pass the data through and let the @media rules in your layout handle the breakpoint; the partial itself stays static. The same scoping discipline carries over if you later move to a Python stack — the Handlebars → Jinja2 migration guide maps @root and @index to their Jinja2 equivalents.

Helpers That Return HTML: SafeString and the XSS Caveat

A helper that builds markup is a common need — a star-rating row, a status badge, a bulletproof button assembled in code. By default Handlebars escapes a helper's string return value, so returning '<b>★</b>' ships <b>★</b> to the inbox. Wrap trusted markup in new Handlebars.SafeString(...) to emit it raw.

// Helper that emits real markup — SafeString prevents double-escaping.
Handlebars.registerHelper('statusBadge', (status) => {
  // Whitelist the input; never interpolate raw user data into a SafeString.
  const palette = { paid: '#16794a', refunded: '#b45309', failed: '#b91c1c' };
  const color = palette[status] || '#64748b';                 // unknown → neutral
  // Gmail/Yahoo strip <head><style>, so style inline on the span itself.
  // Apple Mail / iOS Mail honor the inline color; Samsung Email does too.
  const label = Handlebars.escapeExpression(status);          // escape the dynamic part
  return new Handlebars.SafeString(
    `<span style="color:${color};font-family:Arial,sans-serif;font-weight:700;">${label}</span>`
  );
});

The caveat is the whole point: SafeString disables escaping for everything inside it. The pattern above stays safe only because color comes from a fixed palette and the dynamic status is run through Handlebars.escapeExpression before concatenation. The instant you interpolate un-escaped user input into a SafeString you have reintroduced the exact XSS that double-stache was protecting you from. Treat escapeExpression on every dynamic fragment as mandatory inside any HTML-returning helper.

Layout Engine Alternatives

The hand-rolled render.js above keeps the dependency surface tiny, but two libraries formalize the layout/partial wiring if you prefer convention over code. express-handlebars integrates Handlebars as an Express view engine with a layouts/ and partials/ directory convention and automatic registration — convenient when the same app already serves HTML pages. handlebars-layouts adds {{#extend}}/{{#content}} block inheritance, so a base layout defines named regions that templates override, which scales better than a single {{{body}}} slot once you have several distinct shells.

The trade-off is control. Both libraries register partials by scanning directories, which is exactly what you want until a partial silently fails to load and you have no explicit registration line to inspect. For a high-throughput transactional sender that is decoupled from any web framework, the explicit render.js remains easier to reason about and to wire into a CSS inliner pipeline. Reach for express-handlebars only when the email renderer genuinely lives inside the same Express process as your web views.

More Debugging Entries

Helper output double-escaped — your statusBadge (or any HTML-returning helper) shows <span> in Gmail and Apple Mail instead of a styled badge. The helper returned a plain string, which Handlebars escaped. Wrap the return in new Handlebars.SafeString(...), and escape only the dynamic fragments inside it with Handlebars.escapeExpression.

{{#each}} over undefined throws or renders nothing — a digest email with no notifications key produces an empty body or a Cannot read properties of undefined at compile-call time. Handlebars treats a missing key as falsy, so the loop body is skipped, but a helper that indexes into it can still throw. Default the array in the context (notifications: data.notifications ?? []) before calling render(), and use the {{else}} of {{#each}} to render an empty-state row.

Layout {{{body}}} shows escaped HTML — the message body appears as literal <table> tags in every client. The layout used double-stache ({{body}}) for already-rendered HTML. Switch the body slot to triple-stache ({{{body}}}); it is trusted HTML you generated in step 1 of the pipeline, not user input.

Juice drops a class that has a more specific rule — a .btn style is ignored because a later, more specific selector (.container .btn) won the cascade and Juice inlined that instead. Juice resolves specificity the same way a browser does. Flatten the selector to a single class or raise its specificity to match, then re-check the inlined style="" attribute in the output. This is also why a :hover rule never inlines — there is no element state to inline onto, so keep hover effects in the surviving <style> block for Apple Mail / iOS Mail only.

Media query stripped, mobile layout broken — the responsive resize works in the preview but Apple Mail and iOS Mail show the desktop width. preserveMediaQueries: true was omitted from the Juice call, so the @media block was discarded during inlining. Restore the option, and confirm the @media rule survives in the final <style> block. Note that Gmail's app strips media queries regardless — see responsive email layouts for the fluid-table fallback that does not depend on @media.

FAQ

Should I precompile or cache at runtime? On a long-lived Node server, the runtime templateCache shown above is enough — each template compiles once per process and is reused for the process lifetime. Precompile at build time only for serverless or edge runtimes (Lambda behind SES, Cloudflare Workers) where cold starts dominate and you want to ship handlebars/runtime without the full compiler.

Why do my buttons break in Outlook? Outlook 2016/2019/365 uses the Word rendering engine, which ignores padding on <a> elements, so a CSS-padded link collapses to the text size. Use the table-cell button pattern from the partials/button.hbs example — padding on an <a> wrapped in a <td> with bgcolor — and add VML for a rounded or background-image button. The bulletproof email buttons guide has the full VML fallback.

Is triple-stache ever safe? Yes, for HTML you generated and sanitized yourself — the pre-rendered {{{body}}} slot is the canonical case. It is never safe for user-supplied values. If you must render user rich text, run it through sanitize-html server-side first, then emit the sanitized result.

How do I handle a missing partial in production? A missing partial throws The partial X could not be found at render time, which can take down a send. Register every partial at boot and fail fast on startup if the partials/ directory is incomplete, rather than discovering it on the first send. In staging, compile with { strict: true } so missing variables and partials throw instead of rendering blank.

Can I share helpers between web and email? Yes — keep formatting helpers (formatCurrency, formatDate, t) in a framework-agnostic module and register the same functions into both your web Handlebars instance and the email render.js. Just confirm a single handlebars install (npm ls handlebars); two copies mean a helper registered on one instance is invisible to the other.

Does the templating choice affect deliverability? Not directly — the recipient never sees Handlebars, only the rendered HTML. What affects deliverability is whether that HTML is clean, inlined, and under 102KB, plus your domain authentication. Keep the Jinja2 for Python apps and Handlebars outputs functionally identical so a stack swap never changes what lands in the inbox.

Validation and Deployment Checklist

MJML component architecture — a higher-level abstraction that emits table-driven HTML instead of hand-written tables
Jinja2 for Python apps — the equivalent server-side templating approach in a Python stack
Inline CSS automation — configuring the inliner that runs after the Handlebars compile step
Handlebars → Jinja2 migration — moving an existing Handlebars service onto a Python pipeline

← Back to Modern Email Templating Engines