express-hbs 2.4.2 → 3.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: 'Preview what would be published without actually publishing'
+        required: false
+        type: boolean
+        default: true
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+
+    permissions:
+      # OIDC trusted publishing to npm. Provenance is enabled because this
+      # repository is public; public repos can generate a provenance
+      # attestation at publish time.
+      id-token: write
+      contents: read
+
+    env:
+      FORCE_COLOR: 1
+      CI: true
+      NPM_CONFIG_PROVENANCE: true
+      NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org'
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '24.14.1'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install Corepack
+        run: npm install --global corepack@0.34.6
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --prefer-offline
+
+      - name: Determine whether to publish
+        id: pub
+        run: |
+          name=$(jq -r .name package.json)
+          version=$(jq -r .version package.json)
+          if [ -n "$(npm view "$name@$version" version 2>/dev/null)" ]; then
+            echo "$name@$version is already published; nothing to do"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "queueing $name@$version"
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to npm
+        if: steps.pub.outputs.publish == 'true'
+        # --no-git-checks is required because actions/checkout leaves the repo on
+        # a detached HEAD, which pnpm's default publish branch check rejects.
+        run: pnpm publish --no-git-checks ${{ (github.event.inputs['dry-run'] == 'true' && '--dry-run') || '' }}

package/.github/workflows/test.yml

@@ -1,24 +1,48 @@
 name: Test
+
 on:
   pull_request:
   push:
     branches:
       - main
-      - 'renovate/*'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' || (github.event_name == 'pull_request' && !startsWith(github.head_ref, 'renovate/'))
+    timeout-minutes: 20
     strategy:
+      fail-fast: false
       matrix:
-        node: [ 14, 16, 18 ]
+        node: [20, 22, 24]
     name: Node ${{ matrix.node }}
     steps:
-      - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: ${{ matrix.node }}
-      - run: yarn
-      - run: yarn lint
-      - run: yarn test
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - name: Run tests with coverage
+        run: pnpm coverage
+
+  required-checks-pass:
+    name: Required checks pass
+    if: always()
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Verify all required jobs succeeded
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

package/.nvmrc

@@ -0,0 +1 @@
+20

package/.nycrc.json

@@ -0,0 +1,16 @@
+{
+  "all": true,
+  "include": [
+    "index.js",
+    "lib/**/*.js"
+  ],
+  "branches": 80,
+  "functions": 80,
+  "lines": 80,
+  "statements": 80,
+  "reporter": [
+    "text",
+    "json-summary",
+    "lcov"
+  ]
+}

package/.oxfmtrc.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "singleQuote": true,
+  "tabWidth": 2,
+  "sortPackageJson": false,
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/coverage/**",
+    "pnpm-lock.yaml",
+    "**/*.json",
+    "**/*.jsonc",
+    "**/*.yml",
+    "**/*.yaml",
+    "**/*.md",
+    "**/*.hbs",
+    "**/*.html",
+    "**/*.css"
+  ]
+}

package/.oxlintrc.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn"
+  },
+  "env": {
+    "node": true,
+    "es2024": true
+  },
+  "rules": {
+    "no-console": "error"
+  },
+  "overrides": [
+    {
+      "files": ["test/**/*.js"],
+      "env": {
+        "mocha": true
+      },
+      "rules": {
+        "no-console": "off",
+        "no-unused-vars": "off"
+      }
+    },
+    {
+      "files": ["lib/hbs.js", "example/**/*.js"],
+      "rules": {
+        "no-console": "off"
+      }
+    }
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,40 @@
+# express-hbs agent notes
+
+`express-hbs` is a CommonJS Express view-engine library. Read `README.md` for
+the public API and usage examples before changing behavior.
+
+## Commands
+
+Use pnpm 10 on Node.js 20 or later.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm test
+pnpm coverage
+```
+
+`pnpm test` runs `mocha` and then `pnpm lint` through the `posttest` script.
+`pnpm coverage` runs the same test suite under `nyc` and enforces the coverage
+thresholds in `package.json`.
+
+## Boundaries
+
+- Do not edit `pnpm-lock.yaml` by hand. Regenerate it with `pnpm install`.
+- Keep `lib/hbs.js` and `lib/resolver.js` CommonJS; this package does not use
+  ESM.
+- Treat files under `test/views/**`, `test/issues/**`, and `example/views/**`
+  as rendering fixtures. Seemingly odd whitespace, malformed markup, or partial
+  names may be intentional test coverage.
+- Keep the security warning around user-controlled `layout` values and
+  `restrictLayoutsTo` in sync with behavior.
+
+## Style notes
+
+- Formatting is enforced by `oxfmt`; run `pnpm lint:fix` rather than doing large
+  manual formatting sweeps.
+- The formatter intentionally ignores Handlebars, HTML, CSS, lockfile, and
+  fixture data files. Preserve their existing shape unless the test expectation
+  itself is being changed.
+- Add or update tests for layout resolution, partial loading, async helpers,
+  template options, and caching changes.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2012-2023 Barc, Inc., Ghost Foundation
+Copyright (c) 2012-2025 Barc, Inc., Ghost Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -1,6 +1,17 @@
 # express-hbs
 
-Express handlebars template engine with multiple layouts, blocks and cached partials.
+Express Handlebars template engine for Express apps, with nested layouts,
+named content blocks, cached partials, i18n helpers, and asynchronous helpers.
+
+`express-hbs` exposes Express-compatible view engine functions and a shared
+Handlebars instance. It is used by apps that want Handlebars templates with
+layout inheritance and block-style content regions while keeping the familiar
+`app.engine()` integration.
+
+## Requirements
+
+- Node.js 20 or later
+- pnpm 10 when working on this repository
 
 ## v2.0.0
 
@@ -17,7 +28,8 @@ If you're upgrading from v0.8.4 to v1.0.0 there are some potentially breaking ch
 
 ## Usage
 
-To use with express 4.
+Register the engine with Express using `hbs.express4()`.
+
 ```js
 var hbs = require('express-hbs');
 
@@ -28,7 +40,9 @@ app.engine('hbs', hbs.express4({
 app.set('view engine', 'hbs');
 app.set('views', __dirname + '/views');
 ```
-To use with express 3 is the same as above, except use hbs.express3
+
+`hbs.express3()` is still available for legacy apps and accepts the same
+options:
 
 ```js
 app.engine('hbs', hbs.express3({
@@ -36,13 +50,14 @@ app.engine('hbs', hbs.express3({
 }));
 ```
 
-Options for `#express3` and `#express4`
+Options for `express3()` and `express4()`:
 
 ```js
 hbs.express4({
   partialsDir: "{String/Array} [Required] Path to partials templates, one or several directories",
 
   // OPTIONAL settings
+  restrictLayoutsTo: "{String} Absolute path to a directory to restrict layout directive reading from",
   blockHelperName: "{String} Override 'block' helper name.",
   contentHelperName: "{String} Override 'contentFor' helper name.",
   defaultLayout: "{String} Absolute path to default layout template",
@@ -66,15 +81,15 @@ hbs.express4({
 
 ## Syntax
 
-To mark where layout should insert page
+To mark where a layout should insert page content:
 
     {{{body}}}
 
-To declare a block placeholder in layout
+To declare a block placeholder in a layout:
 
     {{{block "pageScripts"}}}
 
-To define block content in a page
+To define block content in a page:
 
     {{#contentFor "pageScripts"}}
       CONTENT HERE
@@ -82,7 +97,7 @@ To define block content in a page
 
 ## Layouts
 
-There are three ways to use a layout, listed in precedence order
+There are three ways to use a layout, listed in precedence order:
 
 1.  Declarative within a page. Use handlebars comment
 
@@ -99,9 +114,10 @@ There are three ways to use a layout, listed in precedence order
 
 2.  As an option to render
 
-    ## ⚠️ This creates a potential security vulnerability:
-
-    Do not use this option in conjunction with passing user submitted data to res.render e.g. `res.render('index', req.query)`. This allows users to read arbitrary files from your filesystem!
+    ⚠️ Passing user-controlled data into the `layout` option can read arbitrary
+    files unless `restrictLayoutsTo` confines layout resolution to a safe
+    directory. Do not call `res.render('index', req.query)` or similar without
+    setting `restrictLayoutsTo`.
 
     ```js
     res.render('veggies', {
@@ -111,7 +127,8 @@ There are three ways to use a layout, listed in precedence order
     });
     ```
 
-    This option also allows for layout suppression (both the default layout and when specified declaratively in a page) by passing in a falsey Javascript value as the value of the `layout` property:
+    This option also allows layout suppression, including the default layout and
+    template-declared layouts, by passing a falsey JavaScript value:
 
     ```js
     res.render('veggies', {
@@ -214,9 +231,12 @@ var instance2 = hbs.create();
 
 ## Template options
 
-The main use case for template options is setting the handlebars "data" object - this creates global template variables accessible with an `@` prefix.
+The main use case for template options is setting the Handlebars `data` object,
+which creates global template variables accessible with an `@` prefix.
 
-Template options can be set in 3 ways. When setting global template options they can be [passed as config on creation of an instance](https://github.com/barc/express-hbs#usage), and they can also be updated used the `updateTemplateOptions(templateOptions)` method of an instance. To set template options for an individual request they can be set on `res.locals` using the helper method `updateLocalTemplateOptions(locals, templateOptions)`.
+Template options can be passed when creating an engine instance, updated with
+`updateTemplateOptions(templateOptions)`, or set for one request with
+`updateLocalTemplateOptions(locals, templateOptions)` on `res.locals`.
 
 Both of these methods have a companion method `getTemplateOptions()` and `getLocalTemplateOptions(locals)`, which should be used when extending or merging the current options.
 
@@ -274,20 +294,29 @@ File `views/index.hbs`
 
 To run example project
 
-    npm install -d
-    node example/app.js
+```sh
+pnpm install
+node example/app.js
+```
 
+The example server listens on <http://localhost:3000>.
 
 ## Testing
 
-The test suite requires the `grunt-cli` package:
+Install dependencies and run the test suite:
 
-    npm install -g grunt-cli
-    npm install -d
+```sh
+pnpm install
+pnpm test
+```
 
-Once everything's installed, just run:
+Useful maintainer commands:
 
-    npm test
+```sh
+pnpm lint          # oxlint plus oxfmt --check
+pnpm lint:fix      # apply safe lint fixes and formatting
+pnpm coverage      # mocha under nyc with enforced coverage thresholds
+```
 
 
 ## Credits
@@ -301,4 +330,4 @@ Big thanks to all [CONTRIBUTORS](https://github.com/TryGhost/express-hbs/contrib
 
 The MIT License (MIT)
 
-Copyright (c) 2012-2023 Barc, Inc., Ghost Foundation - Released under the [MIT license](LICENSE).
+Copyright (c) 2012-2026 Barc, Inc., Ghost Foundation - Released under the [MIT license](LICENSE).

package/example/app-layoutsDir.js

@@ -1,4 +1,4 @@
-// npm install express express-hbs
+// pnpm add express express-hbs
 
 'use strict';
 
@@ -16,17 +16,20 @@ var viewsDir = relative('views');
 app.use(express.static(relative('public')));
 
 // Hook in express-hbs and tell it where known directories reside
-app.engine('hbs', hbs.express4({
-  partialsDir: [relative('views/partials'), relative('views/partials-other')],
-  layoutsDir: relative('views/layout'),
-  defaultLayout: relative('views/layout/default.hbs')
-}));
+app.engine(
+  'hbs',
+  hbs.express4({
+    partialsDir: [relative('views/partials'), relative('views/partials-other')],
+    layoutsDir: relative('views/layout'),
+    defaultLayout: relative('views/layout/default.hbs'),
+    restrictLayoutsTo: relative('views/layout'),
+  }),
+);
 app.set('view engine', 'hbs');
 app.set('views', relative('views'));
 
-
 // Register sync helper
-hbs.registerHelper('link', function(text, options) {
+hbs.registerHelper('link', function (text, options) {
   var attrs = [];
   for (var prop in options.hash) {
     attrs.push(prop + '="' + options.hash[prop] + '"');
@@ -35,66 +38,57 @@ hbs.registerHelper('link', function(text, options) {
 });
 
 // Register Async helpers
-hbs.registerAsyncHelper('readFile', function(filename, cb) {
-  fs.readFile(fp.join(viewsDir, filename), 'utf8', function(err, content) {
+hbs.registerAsyncHelper('readFile', function (filename, cb) {
+  fs.readFile(fp.join(viewsDir, filename), 'utf8', function (err, content) {
     if (err) console.error(err);
     cb(new hbs.SafeString(content));
   });
 });
 
-var fruits = [
-  {name: 'apple'},
-  {name: 'orange'},
-  {name: 'pear'}
-];
-
+var fruits = [{ name: 'apple' }, { name: 'orange' }, { name: 'pear' }];
 
-var veggies = [
-  {name: 'asparagus'},
-  {name: 'carrot'},
-  {name: 'spinach'}
-];
+var veggies = [{ name: 'asparagus' }, { name: 'carrot' }, { name: 'spinach' }];
 
-app.get('/', function(req, res) {
+app.get('/', function (req, res) {
   res.render('index', {
-    title: 'express-hbs example'
+    title: 'express-hbs example',
   });
 });
 
-app.get('/fruits', function(req, res) {
+app.get('/fruits', function (req, res) {
   res.render('fruits/index-layoutsDir', {
     title: 'My favorite fruits',
-    fruits: fruits
+    fruits: fruits,
   });
 });
 
-app.get('/fruits/:name', function(req, res) {
-    res.render('fruits/details-layoutsDir', {
-        fruit: req.params.name
-    });
+app.get('/fruits/:name', function (req, res) {
+  res.render('fruits/details-layoutsDir', {
+    fruit: req.params.name,
+  });
 });
 
-app.get('/veggies', function(req, res) {
+app.get('/veggies', function (req, res) {
   res.render('veggies', {
     title: 'My favorite veggies',
     veggies: veggies,
-    layout: 'veggie'
+    layout: 'veggie',
   });
 });
 
-app.get('/veggies/explicit-dir', function(req, res) {
+app.get('/veggies/explicit-dir', function (req, res) {
   res.render('veggies', {
     title: 'My favorite veggies',
     veggies: veggies,
-    layout: relative('views/layout/veggie')
+    layout: relative('views/layout/veggie'),
   });
 });
 
-app.get('/veggies/:name', function(req, res) {
-    res.render('veggies/details', {
-        veggie: req.params.name,
-        layout: 'veggie-details'
-    });
+app.get('/veggies/:name', function (req, res) {
+  res.render('veggies/details', {
+    veggie: req.params.name,
+    layout: 'veggie-details',
+  });
 });
 
 if (require.main === module) {

package/example/app.js

@@ -1,5 +1,5 @@
 'use strict';
-// npm install express express-hbs
+// pnpm add express express-hbs
 
 function create(hbs, env) {
   if (env) process.env.NODE_ENV = env;
@@ -18,81 +18,75 @@ function create(hbs, env) {
   app.use(express.static(relative('public')));
 
   // Hook in express-hbs and tell it where known directories reside
-  app.engine('hbs', hbs.express4({
-    partialsDir: [relative('views/partials'), relative('views/partials-other')],
-    defaultLayout: relative('views/layout/default.hbs')
-  }));
+  app.engine(
+    'hbs',
+    hbs.express4({
+      partialsDir: [relative('views/partials'), relative('views/partials-other')],
+      defaultLayout: relative('views/layout/default.hbs'),
+      restrictLayoutsTo: viewsDir,
+    }),
+  );
   app.set('view engine', 'hbs');
   app.set('views', viewsDir);
 
   // Register sync helper
-  hbs.registerHelper('link', function(text, options) {
+  hbs.registerHelper('link', function (text, options) {
     var attrs = [];
     for (var prop in options.hash) {
       attrs.push(prop + '="' + options.hash[prop] + '"');
     }
-    return new hbs.SafeString(
-      '<a ' + attrs.join(' ') + '>' + text + '</a>'
-    );
+    return new hbs.SafeString('<a ' + attrs.join(' ') + '>' + text + '</a>');
   });
 
   // Register Async helpers
-  hbs.registerAsyncHelper('readFile', function(filename, cb) {
-    fs.readFile(fp.join(viewsDir, filename), 'utf8', function(err, content) {
+  hbs.registerAsyncHelper('readFile', function (filename, cb) {
+    fs.readFile(fp.join(viewsDir, filename), 'utf8', function (err, content) {
       if (err) console.error(err);
       cb(new hbs.SafeString(content));
     });
   });
 
-  var fruits = [
-    {name: 'apple'},
-    {name: 'orange'},
-    {name: 'pear'}
-  ];
+  var fruits = [{ name: 'apple' }, { name: 'orange' }, { name: 'pear' }];
 
-  var veggies = [
-    {name: 'asparagus'},
-    {name: 'carrot'},
-    {name: 'spinach'}
-  ];
+  var veggies = [{ name: 'asparagus' }, { name: 'carrot' }, { name: 'spinach' }];
 
-  app.get('/', function(req, res) {
+  app.get('/', function (req, res) {
     res.render('index', {
-      title: 'express-hbs example'
+      title: 'express-hbs example',
     });
   });
 
-  app.get('/replace', function(req, res) {
+  app.get('/replace', function (req, res) {
     res.render('replace', {
-      title: 'express-hbs example'
+      title: 'express-hbs example',
     });
   });
 
-  app.get('/fruits', function(req, res) {
+  app.get('/fruits', function (req, res) {
     res.render('fruits/index', {
       title: 'My favorite fruits',
-      fruits: fruits
+      fruits: fruits,
     });
   });
 
-  app.get('/fruits/:name', function(req, res) {
+  app.get('/fruits/:name', function (req, res) {
     res.render('fruits/details', {
-      fruit: req.params.name
+      fruit: req.params.name,
     });
   });
 
-  app.get('/veggies', function(req, res) {
+  app.get('/veggies', function (req, res) {
     res.render('veggies', {
       title: 'My favorite veggies',
       veggies: veggies,
-      layout: 'layout/veggie'
+      layout: 'layout/veggie',
     });
   });
 
-  app.get('/veggies/:name', function(req, res) {
+  app.get('/veggies/:name', function (req, res) {
     res.render('veggies/details', {
       veggie: req.params.name,
-      layout: 'layout/veggie-details'
+      layout: 'layout/veggie-details',
     });
   });