Skip to content
Merged
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 85 additions & 63 deletions HISTORY.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,56 @@
unreleased
==================
5.0.0
=====

* deps: handlebars@4.7.8
- Make library compatible with workers
- Don't rely on Node.js global object
- Fix compiling of each block params in strict mode
- Fix rollup warning when importing Handlebars as ESM
- Fix bundler issue with webpack 5
- Use https instead of git for mustache submodule
- BREAKING: prototype-access is now disabled by default. hbs no longer sets `allowProtoMethodsByDefault` and `allowProtoPropertiesByDefault` to `true`, so handlebars' defaults apply: templates no longer read inherited (prototype) members of the data, and handlebars logs a warning the first time a lookup of a given property is blocked. Opt back in per instance via `runtimeOptions`.
- BREAKING: require Node.js >= 18
- BREAKING: target Express 5 and remove the legacy Express 2.x `compile()` engine method
Comment thread
UlisesGascon marked this conversation as resolved.
Resolved
- BREAKING: remove the deprecated `hbs.SafeString` and `hbs.Utils` aliases. Use `hbs.handlebars.SafeString` and `hbs.handlebars.Utils` instead.
- BREAKING: async helper callbacks called with two arguments are now error-first (`cb(err, result)`), so a truthy first argument fails the render. Callbacks called with a single argument (`cb(result)`) are unchanged.

4.2.0 / 2021-11-16
==================
4.4.0
=====

- deps: handlebars@4.7.10 ([#283](https://github.com/pillarjs/hbs/pull/283))
- addresses [CVE-2026-106445](https://www.cve.org/CVERecord?id=CVE-2026-106445) ([GHSA-p8wg-vrv2-v86f](https://github.com/advisories/GHSA-p8wg-vrv2-v86f)), [GHSA-8r5x-fm3f-whwj](https://github.com/advisories/GHSA-8r5x-fm3f-whwj), and [GHSA-xw65-4hp5-5hc7](https://github.com/advisories/GHSA-xw65-4hp5-5hc7)
- Add `compileOptions` instance option forwarded to `handlebars.compile()` ([#268](https://github.com/pillarjs/hbs/pull/268))
- Add `runtimeOptions` instance option forwarded to the compiled template at render time. This can restore handlebars' safer prototype-access defaults by setting `allowProtoMethodsByDefault` and `allowProtoPropertiesByDefault` to `false` ([#284](https://github.com/pillarjs/hbs/pull/284))

4.3.1
=====

- Fix [CVE-2026-87123](https://www.cve.org/CVERecord?id=CVE-2026-87123) ([GHSA-3c55-w9jx-p5jr](https://github.com/pillarjs/hbs/security/advisories/GHSA-3c55-w9jx-p5jr))
- fix treat async substitution throws as render errors

4.3.0
=====

- Fix [CVE-2026-16231](https://www.cve.org/CVERecord?id=CVE-2026-16231) ([GHSA-rg36-rxv9-2m9q](https://github.com/pillarjs/hbs/security/advisories/GHSA-rg36-rxv9-2m9q))

4.2.1
=====

* deps: handlebars@4.7.9

4.2.0
=====

* Add `rename` option to `registerPartials`
* Ensure all partials are registered before rendering
* Fix function context in async helpers
* deps: walk@2.3.15

4.1.2 / 2021-04-15
==================
4.1.2
=====

* deps: handlebars@4.7.7

4.1.1 / 2020-04-03
==================
4.1.1
=====

* deps: handlebars@4.7.6

4.1.0 / 2020-01-14
==================
4.1.0
=====

* deps: handlebars@4.5.3
- Add `handlebars.parseWithoutProcessing`
Expand All @@ -39,15 +61,15 @@ unreleased
- Fix work-around for `constructor` blocking
- Validate arguments to `#if`, `#unless` and `#with` helpers

4.0.6 / 2019-10-09
==================
4.0.6
=====

* deps: handlebars@4.3.5
- Fix error object inheritance
- Fix work-around for `constructor` blocking

4.0.5 / 2019-09-27
==================
4.0.5
=====

* Fix async helpers not working when cache enabled
* Fix handling of exceptions from layout
Expand All @@ -57,115 +79,115 @@ unreleased
- Fix work-around for `constructor` blocking
* deps: walk@2.3.14

4.0.4 / 2019-04-14
==================
4.0.4
=====

* deps: handlebars@4.0.14
- Block `constructor` property using `lookup`

4.0.3 / 2019-03-01
==================
4.0.3
=====

* Fix path for partials multiple dirs deep on Windows

4.0.2 / 2019-02-18
==================
4.0.2
=====

* deps: handlebars@4.0.13

4.0.1 / 2016-09-18
==================
4.0.1
=====

* Support params for async helper
* deps: handlebars@4.0.5
* deps: walk@2.3.9

4.0.0 / 2015-11-02
==================
4.0.0
=====

* Fix caching of non default filename layouts
* deps: handlebars@4.0.3

3.1.1 / 2015-09-11
==================
3.1.1
=====

* Fix `localsAsTemplateData` when cache is enabled

3.1.0 / 2015-06-10
==================
3.1.0
=====

* Make `@data` available to layouts

3.0.1 / 2015-03-12
==================
3.0.1
=====

* Fix using custom extensions when using view engine layouts

3.0.0 / 2015-03-09
==================
3.0.0
=====

* deps: handlebars@3.0.0

2.9.0 / 2015-03-06
==================
2.9.0
=====

* Scope internal async tracker to per middleware
* Support multiple view folders from Express

2.8.0 / 2014-12-26
==================
2.8.0
=====

* Scope internal async tracker to per hbs instance
* deps: handlebars@2.0.0

2.7.0 / 2014-06-02
==================
2.7.0
=====

* Fix registering directories of partials on Windows
* Add API to expose locals as template data

2.6.0 / 2014-04-06
==================
2.6.0
=====

* Fix support for custom handlebars instance

2.5.0 / 2014-02-19
==================
2.5.0
=====

* deps: handlebars@1.3.0

2.4.0 / 2013-09-13
==================
2.4.0
=====

* Add support for multi-level partial paths

2.3.1 / 2013-08-01
==================
2.3.1
=====

* deps: after@0.8.1
* deps: handlebars@1.0.12

2.3.0 / 2013-05-30
==================
2.3.0
=====

* Add `registerPartials`

2.1.0 / 2013-03-19
==================
2.1.0
=====

* Add `create` for multiple instances

2.0.2 / 2013-02-21
==================
2.0.2
=====

* deps: handlebars@1.0.9

2.0.1 / 2012-11-30
==================
2.0.1
=====

* Ignore layout error when not using layout

2.0.0 / 2012-11-21
==================
2.0.0
=====

* deps: handlebars@1.0.7
92 changes: 92 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,25 @@ app.set('view engine', 'html')
app.engine('html', require('hbs').__express)
```

## Security ##

hbs is a thin wrapper around [handlebars](https://handlebarsjs.com/), so its
[prototype-access security options](https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access)
apply. Two points are worth calling out:

- **Prototype access.** hbs does not set `allowProtoMethodsByDefault` or
`allowProtoPropertiesByDefault`, so handlebars' own defaults apply: inherited
(prototype) members of the data are not readable from templates, and
handlebars logs a warning the first time a lookup of a given property is
blocked. If your templates need to read inherited members, opt in through
[Runtime options](#runtime-options). (hbs 4.x set both to `true`; 5.0
restores the safer handlebars defaults.)
- **HTML escaping.** `{{expression}}` output is HTML-escaped by default. Do not
enable `noEscape` (see [Compile options](#compile-options)) for untrusted data.

In all cases, treat both the template and the template context as trusted input:
do not compile templates from, or render untrusted data through, untrusted sources.

## Helpers and Partials ##

hbs exposes the `registerHelper` and `registerPartial` method from handlebars.
Expand Down Expand Up @@ -117,6 +136,79 @@ If you wish to use handlebars methods like `SafeString` please do so on this pro
hbs.handlebars === require('handlebars');
```

## Compile options ##

Options for [`handlebars.compile()`](https://handlebarsjs.com/api-reference/compilation.html)
(such as `strict`, `noEscape` or `preventIndent`) can be set per instance. They apply to
every view and layout compiled by that instance.

```js
const hbs = require('hbs')

const instance = hbs.create(null, {
compileOptions: { strict: true },
})

app.engine('hbs', instance.__express)
```

Note that `noEscape: true` disables HTML escaping for every `{{expression}}` rendered by the
instance, so only use it when the data is trusted.

The options are also exposed as the `compileOptions` property, which can be changed at any
time (compiled templates already in the cache are not affected):

```js
hbs.compileOptions = { noEscape: true }
```

## Runtime options ##

[Runtime options](https://handlebarsjs.com/api-reference/runtime-options.html) passed to the
compiled template at render time can be set per instance. The most relevant ones are the
prototype-access controls.

hbs sets none of them itself, so handlebars' safe prototype-access defaults apply: inherited
(prototype) properties and methods of the data are blocked, and handlebars logs a warning to
the console the first time a lookup of a given property is blocked. Setting
`allowProtoMethodsByDefault` or `allowProtoPropertiesByDefault` to any value, including
`false`, disables that warning.

If your templates need to read inherited members, opt in per instance:

```js
const hbs = require('hbs')

const instance = hbs.create(null, {
runtimeOptions: {
allowProtoMethodsByDefault: true,
allowProtoPropertiesByDefault: true,
},
})

app.engine('hbs', instance.__express)
```

To allow only a few known inherited members instead of re-enabling everything, use
handlebars' `allowedProtoProperties` / `allowedProtoMethods` allowlists:

```js
hbs.create(null, {
runtimeOptions: {
allowedProtoProperties: { myField: true },
},
})
```

As with `compileOptions`, the options are exposed as the `runtimeOptions` property and can be
changed at any time:

```js
hbs.runtimeOptions = { allowProtoPropertiesByDefault: true }
```

Regardless of these options, do not render untrusted data as the template context.

## Recipes ##

### more than one instance ###
Expand Down
Loading
Loading