or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

express-integration.mdhelper-management.mdindex.mdpartial-management.md
tile.json

tessl/npm-hbs

Express.js template engine plugin for Handlebars

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/hbs@4.2.x

To install, run

npx @tessl/cli install tessl/npm-hbs@4.2.0

index.mddocs/

hbs

hbs is an Express.js view engine that provides seamless integration with Handlebars templates. It enables developers to use Handlebars as the template engine in Express applications with features like helper registration, partial template support, local data exposure through the @property syntax, isolated instances, and layout system integration.

Package Information

  • Package Name: hbs
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install hbs

Core Imports

const hbs = require('hbs');

For ES modules (if supported by your environment):

import hbs from 'hbs';

Basic Usage

const express = require('express');
const hbs = require('hbs');

const app = express();

// Set hbs as the view engine
app.set('view engine', 'hbs');

// Optionally set views directory
app.set('views', './views');

// Register a helper
hbs.registerHelper('capitalize', function(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
});

// Register partials from a directory
hbs.registerPartials(__dirname + '/views/partials');

// Enable locals as template data
hbs.localsAsTemplateData(app);
app.locals.siteName = 'My Site';

app.get('/', (req, res) => {
  res.render('index', { title: 'Home', message: 'Welcome!' });
});

Architecture

hbs is built around several key components:

  • Instance System: Each hbs instance maintains isolated template cache, helpers, and partials for multi-tenant support
  • Express Integration: Native Express view engine compliance with 
    __express
    middleware and automatic layout resolution
  • Handlebars Proxy: Direct access to underlying Handlebars functionality while adding Express-specific features
  • Template Caching: Automatic template compilation caching based on Express cache settings for performance optimization
  • Layout System: Built-in layout template support with flexible resolution from multiple view directories
  • Async Helper Support: Asynchronous helper registration with automatic coordination using placeholder replacement and callback batching
  • Async Queue System: Prevents race conditions during partial registration with automatic request queuing

Capabilities

Express View Engine

Core Express.js view engine integration providing template rendering, caching, and layout support.

// Main view engine middleware function
function __express(filename, options, callback);

// Create isolated hbs instance  
function create(handlebars);

Express Integration

Helper Management

Register and manage Handlebars helper functions, including asynchronous helpers with callback support.

// Register synchronous helper
function registerHelper(name, helper);

// Register asynchronous helper with callback
function registerAsyncHelper(name, helper);

Helper Management

Partial Management

Register and manage Handlebars partial templates, including bulk registration from directories with custom naming.

// Register single partial
function registerPartial(name, template);

// Register all partials from directory
function registerPartials(directory, options, callback);

Partial Management

Template Compilation

Direct template compilation support for Express 2.x compatibility and custom use cases.

// Compile template string to render function
function compile(template);

Layout System

Automatically handles layout templates with flexible resolution from multiple view directories and configurable layout options.

// Layout resolution via render options or app settings
// Default: layout.hbs, Custom: { layout: 'custom' }, None: { layout: false }
// Uses Express view settings and supports multiple view directories

Locals as Template Data

Enable access to Express app.locals and res.locals in templates using the @property syntax for global application data.

// Enable locals access in templates with @ syntax
function localsAsTemplateData(app);

Global Types

// hbs instance interface
interface HbsInstance {
  // Direct access to underlying Handlebars instance
  handlebars: HandlebarsStatic;
  
  // Template cache storage
  cache: { [filename: string]: HandlebarsTemplateDelegate };
  
  // Express view engine middleware
  __express: (filename: string, options: RenderOptions, callback: (err: Error | null, result?: string) => void) => void;
  
  // Helper registration methods
  registerHelper: (name: string, helper: Function) => void;
  registerAsyncHelper: (name: string, helper: Function) => void;
  
  // Partial registration methods  
  registerPartial: (name: string, template: string) => void;
  registerPartials: (directory: string, options?: PartialOptions | ((err?: Error) => void), callback?: (err?: Error) => void) => void;
  
  // Template compilation
  compile: (template: string | Function) => Function;
  
  // Express integration utilities
  localsAsTemplateData: (app: ExpressApp) => void;
  
  // Deprecated properties (for backwards compatibility)
  SafeString: Function; // deprecated - use handlebars.SafeString instead
  Utils: any; // deprecated - use handlebars.Utils instead
}

// Partial registration options
interface PartialOptions {
  rename?: (name: string) => string;
}

// Express render options (subset of relevant options)
interface RenderOptions {
  cache?: boolean;
  layout?: string | false;
  settings?: {
    views?: string | string[];
    'view options'?: {
      layout?: string | false;
    };
  };
  _locals?: any;
}

// Express app interface (minimal relevant parts)
interface ExpressApp {
  locals: any;
  render: Function;
}