or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

express-integration.mddocs/

Express Integration

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