express-handlebars

express-handlebars is a Handlebars template engine built specifically for Express, filling the gap left when Express 3.x dropped built-in view-engine concepts like layouts and partials. It exposes an engine factory (engine()), a convenience instance creator (create()), and the underlying ExpressHandlebars class, so simple apps can register a single engine call while advanced apps get direct access to caching, helper registration, and template compilation internals.

The library is fully async and non-blocking: file reads and directory scans use graceful-fs and glob under promises, with an internal file-system cache that avoids redundant I/O. In development, templates are always reloaded from disk; in production (or with view cache enabled), raw files and compiled/precompiled templates are cached aggressively, including nested partials directories and multi-directory partial sources with custom namespacing and renaming.

What You Get

• A drop-in Express view engine registered via app.engine('handlebars', engine()), with sensible defaults for views, partials, and layouts directories.
• Layout support restored from pre-3.x Express, controlled per-request via the layout render option or globally via defaultLayout.
• Nested and multi-directory partials, including namespacing and custom rename functions for partial names.
• Instance-level and render-level helper registration, merged together at render time so per-request overrides are trivial.
• Template and partial precompilation for sharing compiled Handlebars templates with client-side code.
• A metadata channel ({{@exphbs}}) exposing cache state, encoding, view name, layout, and the helpers/partials used for the current render.

Common Use Cases

• Server-rendered Express applications that need a shared HTML layout wrapping page-specific content.
• Multi-tenant or modular apps that source partials from more than one directory with namespacing to avoid collisions.
• Apps needing precompiled Handlebars templates shipped to the browser for shared server/client rendering logic.
• Migrating legacy Express 2.x view-engine code that relied on built-in layout support Express 3.x removed.

Under The Hood

Architecture The library centers on a single ExpressHandlebars class (lib/express-handlebars.ts) that Express registers via a bound engine method (this.engine = this.renderView.bind(this)). renderView() resolves the view name relative to Express’s settings.views, merges instance- and render-level helpers/partials, renders the view, then recursively renders any resolved layout with the view’s output injected as body — a two-pass render rather than a nested-template mechanism. Public methods (getTemplate, getTemplates, getPartials, render) are deliberately exposed so advanced consumers can bypass renderView entirely, and protected hooks (_compileTemplate, _precompileTemplate, _renderTemplate) let subclasses swap in custom Handlebars behavior without forking the class.

Tech Stack Written in TypeScript (~97% of the codebase) targeting ES2015/CommonJS output via tsc, with three runtime dependencies: handlebars for compilation, graceful-fs for resilient file reads, and glob for partials/directory discovery. Node 22.23+ is required per engines. Tests run on Jest with ts-jest, and eslint (flat config via eslint.config.mjs) plus typescript-eslint enforce lint rules; releases are automated with semantic-release and its changelog/git/npm/github plugins wired through GitHub Actions.

Code Quality The Jest config enforces a strict 100% coverage threshold across branches, functions, lines, and statements, and the spec suite (spec/express-handlebars.test.ts) exercises caching, error paths (e.g. invalid partialsDir types), and multi-source partials directly against fixture template files rather than mocks. Errors are explicit Error throws with descriptive messages rather than silent fallbacks, and all public async methods are typed via types/index.d.ts, giving callers real IntelliSense over render options, template caches, and helper objects.

What Makes It Unique Unlike generic Handlebars wrappers, this package explicitly re-engineers the layout/partials concepts Express removed in its 3.x rewrite, while keeping the entire implementation surface (compile/precompile/render hooks, file-system cache, template name resolution) overridable rather than hidden behind a black-box function. The {{@exphbs}} metadata channel and precompilation support for client-shared templates are comparatively rare among Express template-engine adapters, most of which only wrap Handlebars.compile without exposing caching or layout internals.