tessl/npm-hbs

Express.js template engine plugin for Handlebars

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Express Integration

Name: tessl/npm-hbs
Author: tessl

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

Capabilities

View Engine Middleware

The main Express view engine middleware function that handles template rendering.

/**
 * Express view engine middleware function
 * @param filename - Path to template file to render
 * @param options - Render options including locals and Express settings
 * @param callback - Callback function to return rendered content or error
 */
function __express(filename, options, callback);

Usage Example:

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

const app = express();

// Set as default view engine (uses __express automatically)
app.set('view engine', 'hbs');

// Or register for specific file extension
app.engine('html', hbs.__express);

Instance Creation

Create isolated hbs instances with independent template caches, helpers, and partials.

/**
 * Create new isolated hbs instance
 * @param handlebars - Optional custom Handlebars instance to use
 * @returns New hbs instance with isolated state
 */
function create(handlebars);

Usage Example:

const hbs = require('hbs');

// Create isolated instances
const instance1 = hbs.create();
const instance2 = hbs.create();

app.engine('hbs', instance1.__express);
app.engine('html', instance2.__express);

// Each instance has separate helpers and partials
instance1.registerHelper('helper1', () => 'Instance 1');
instance2.registerHelper('helper1', () => 'Instance 2');

Locals as Template Data

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

/**
 * Enable locals as template data
 * @param app - Express application instance
 */
function localsAsTemplateData(app);

Usage Example:

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

// Enable locals access in templates
hbs.localsAsTemplateData(app);

// Set global data
app.locals.siteName = 'My Site';
app.locals.version = '1.0.0';

// In templates, access with @ syntax:
// {{@siteName}} outputs "My Site"
// {{@version}} outputs "1.0.0"

app.get('/page', (req, res) => {
  res.locals.pageTitle = 'Page Title';
  res.render('page'); // Template can access {{@pageTitle}}
});

Template Compilation (Express 2.x)

Direct template compilation for Express 2.x compatibility and custom rendering scenarios.

/**
 * Compile template string to render function (Express 2.x compatibility)
 * @param template - Template string or compiled template function
 * @returns Render function that accepts locals and returns rendered string
 */
function compile(template);

Usage Example:

const hbs = require('hbs');

// Compile template directly
const template = hbs.compile('Hello {{name}}!');

// Render with locals
const result = template({ name: 'World' });
console.log(result); // "Hello World!"

Layout System

hbs automatically handles layout templates with flexible resolution from multiple view directories.

Layout Resolution:

Default layout file: layout.hbs (or layout + current template extension)
Custom layout: specify in render options { layout: 'custom' }
No layout: specify { layout: false }
Global layout setting: via app.set('view options', { layout: 'global' })

Usage Example:

// Default layout (views/layout.hbs)
app.get('/', (req, res) => {
  res.render('index'); // Uses layout.hbs
});

// Custom layout
app.get('/admin', (req, res) => {
  res.render('admin', { layout: 'admin-layout' });
});

// No layout
app.get('/api/docs', (req, res) => {
  res.render('api-docs', { layout: false });
});

Template Caching

Automatic template compilation caching based on the cache option from Express settings.

Cache Behavior:

Templates are cached when options.cache is true
Cache is per-instance (isolated between hbs instances)
Cache key is the full file path
Cached templates skip file reading and compilation

Usage Example:

// Enable caching in production
if (app.get('env') === 'production') {
  app.set('view cache', true);
}

// Cache setting affects hbs automatically
// Cached templates render faster on subsequent requests

Error Handling

All template errors are enhanced with filename context for better debugging.

Error Enhancement:

Template compilation errors include filename
Template rendering errors include filename
File not found errors include attempted path

Example Error:

Error: /path/to/views/template.hbs: Parse error on line 5: Unexpected token

docs

express-integration.md

helper-management.md

index.md

partial-management.md

tile.json

tessl/npm-hbs