express-hbs-compile

express-hbs-compile

Compile Handlebars templates into HTML strings, powered by express-hbs.

Installation

npm install express-hbs-compile

Quick Start

Import the package and call compile() with the path to your template directory. This returns an async render function that compiles a Handlebars template into an HTML string.

import path from 'path';
import compile from 'express-hbs-compile';

// 1. Create a render function by specifying where your templates live.
const render = compile({
  viewsDir: path.join(import.meta.dirname, 'views'),
});

// 2. Render a template with data — returns a Promise<string>.
const html = await render('index.hbs', {title: 'Home'});
console.log(html); // => compiled HTML string

Note: import.meta.dirname requires Node 20.11+. For older versions, use __dirname (CommonJS) or dirname(fileURLToPath(import.meta.url)) (ESM).

CommonJS is also supported: const compile = require('express-hbs-compile');

API

compile(options)

Creates a render function bound to the given options. All paths except viewsDir have sensible defaults and are optional.

const render = compile({
  viewsDir: path.join(import.meta.dirname, 'views'),
  partialsDir: path.join(import.meta.dirname, 'views/partials'),
  layoutsDir: path.join(import.meta.dirname, 'views/layout'),
  defaultLayout: path.join(import.meta.dirname, 'views/layout/default.hbs'),
  extname: '.hbs',
  helpers: {
    shout: str => str.toUpperCase() + '!',
  },
});

Options

Name	Type	Required	Default	Description
viewsDir	string	Yes		Absolute path to the template directory.
partialsDir	string | string[]	No	<viewsDir>/partials	Absolute path(s) to partial template directories.
layoutsDir	string	No	<viewsDir>/layout	Absolute path to the layout template directory.
defaultLayout	string	No	<layoutsDir>/default.hbs	Absolute path to the default layout file.
extname	string	No	.hbs	File extension for templates.
contentHelperName	string	No	contentFor	Name of the content block helper.
blockHelperName	string	No	block	Name of the block rendering helper.
helpers	{[name: string]: Function}	No		Custom Handlebars helpers to register.

Returns

(template: string, data?: object) => Promise<string> — an async render function.

Throws

• TypeError — if viewsDir is not provided.
• TypeError — if any specified directory or file does not exist.

render(template, data?)

The function returned by compile(). Compiles a template and returns the resulting HTML string.

// Relative path (resolved from viewsDir)
const html = await render('user/profile.hbs', {username: 'John'});

// Absolute path also works
const welcome = await render(path.join(import.meta.dirname, 'views/email/welcome.hbs'), {
  recipientName: 'John',
});

Parameters

Name	Type	Required	Description
template	string	Yes	File name or absolute path to the template. Relative names are resolved from viewsDir.
data	object	No	Data passed to the template. settings, cache, and layout are reserved keys.

Returns

Promise<string> — the compiled HTML string.

Throws

• TypeError — if the template file does not exist.
• TypeError — if data contains a reserved key (settings, cache, or layout).

Built-in Helpers

The internal Handlebars instance is extended with handlebars-extd, which provides additional helpers like eq, ne, gt, gte, lt, lte, and more.

{{#if (eq role 'admin')}}
  <span>Admin</span>
{{/if}}

Changelog

See CHANGELOG.md.

Author

shumatsumonobu

• github/shumatsumonobu
• x/shumatsumonobu
• facebook/takuya.motoshima.7

License

MIT