How to Contribute

Reporting Security Issues

Please refer to our Security Policy.

Reporting Issues

Please refer to our FAQ for common issues that people run into.

Should you run into other issues with the project, please don't hesitate to let us know by filing an issue!

In general, we are going to ask for an example of the problem failing, which can be as simple as a jsfiddle/jsbin/etc. We've put together a jsfiddle template to ease this. (We will keep this link up to date as new releases occur, so feel free to check back here).

Pull requests containing only failing tests demonstrating the issue are welcomed and this also helps ensure that your issue won't regress in the future once it's fixed.

Documentation issues on the handlebarsjs.com site should be reported on handlebars-lang/docs.

Branches

• The branch master contains the current development version (v5).
• The branch 4.x contains the previous stable version. Only critical bugfixes are backported there.

Pull Requests

We also accept pull requests!

Generally we like to see pull requests that

• Maintain the existing code style
• Are focused on a single change (i.e. avoid large refactoring or style adjustments in untouched code if not the primary goal of the pull request)
• Have good commit messages
• Have tests
• Don't significantly decrease the current code coverage (see coverage/lcov-report/index.html)

Building

To build Handlebars.js you'll need Node.js installed.

Before building, you need to make sure that the Git submodule spec/mustache is included (i.e. the directory spec/mustache should not be empty). To include it, if using Git version 1.6.5 or newer, use git clone --recursive rather than git clone. Or, if you already cloned without --recursive, use git submodule update --init.

This project uses pnpm as its package manager (the required version is pinned in the packageManager field of package.json). The easiest way to get the right version is via Corepack, which ships with Node.js: run corepack enable once, and pnpm commands will automatically use the pinned version.

Note: While Handlebars itself supports Node.js >=20 at runtime (see engines in package.json), the development tooling requires a newer Node.js for the pinned pnpm version: pnpm 11 requires Node.js >=22.13. Use Node.js 22.13 or later when building and testing locally.

Project dependencies may be installed via pnpm install.

To build Handlebars.js from scratch, run pnpm run build in the root of the project. That will compile CJS modules via SWC and bundle UMD distributions via rspack, outputting results to the dist/ folder. To run tests, use pnpm test.

If you notice any problems, please report them to the GitHub issue tracker at http://github.com/handlebars-lang/handlebars.js/issues.

Running Tests

To run tests locally, first install all dependencies.

pnpm install

Clone the mustache specs into the spec/mustache folder.

cd spec
rm -r mustache
git clone https://github.com/mustache/spec.git mustache

From the root directory, run the tests.

pnpm test

Linting and Formatting

Handlebars uses oxlint for linting, oxfmt for formatting, and eslint (with eslint-plugin-compat) for browser API compatibility checks. Committed files are linted and formatted in a pre-commit hook.

You can use the following scripts to make sure that the CI job does not fail:

• pnpm run lint will run all linters and fail on warnings
• pnpm run format will format all files
• pnpm run check-before-pull-request will perform all checks that our CI job does, excluding integration tests.
• pnpm run test:integration will run integration tests (bundler compatibility with webpack, rollup, etc.) These tests only work on Linux.

Releasing the latest version

Before attempting the release Handlebars, please make sure that you have the following authorizations:

• Push-access to handlebars-lang/handlebars.js
• Publishing rights on npmjs.com for the handlebars package
• Publishing rights on gemfury for the handlebars-source package
• Push-access to the repo for legacy package managers: components/handlebars
• Push-access to the production-repo of the handlebars site: handlebars-lang/handlebarsjs.com-github-pages

When releasing a previous version of Handlebars, please look into the CONTRIBUNG.md in the corresponding branch.

A full release may be completed with the following:

pnpm install --frozen-lockfile
pnpm run build
pnpm publish

After the release, you should check that all places have really been updated. Especially verify that the latest-tags in those places still point to the latest version

• The npm-package (check latest-tag)
• The bower package (check the package.json)
• The AWS S3 Bucket (check latest-tag)
• RubyGems

When everything is OK, the handlebars site needs to be updated.

Go to the master branch of the repo handlebars-lang/docs and make a minimal change to the README. This will invoke a github-action that redeploys the site, fetching the latest version-number from the npm-registry. (note that the default-branch of this repo is not the master and regular changes are done in the handlebars-lang/docs-repo).