# handlebars-loader

> handlebars loader module for webpack

Latest version **1.7.3** (published 2022-12-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install handlebars-loader
pnpm add handlebars-loader
yarn add handlebars-loader
bun add handlebars-loader
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.7.3 |
| Published | 2022-12-08 |
| First published | 2013-05-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 22.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 558 |
| Maintainers | altano, diurnalist, pcardune |

## Links

- npm: https://www.npmjs.com/package/handlebars-loader
- Repository: https://github.com/pcardune/handlebars-loader
- Issues: https://github.com/pcardune/handlebars-loader/issues
- npm.io page: https://npm.io/package/handlebars-loader

## Dependencies (4)

- [async](https://npm.io/package/async.md) ^3.2.2
- [fastparse](https://npm.io/package/fastparse.md) ^1.0.0
- [loader-utils](https://npm.io/package/loader-utils.md) 1.4.x
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.0

## Recent versions

- 1.7.3 (latest) — 2022-12-08
- 1.7.2 — 2022-05-18
- 1.7.1 — 2018-12-18
- 1.7.0 — 2018-03-20
- 1.6.0 — 2017-09-01
- 1.5.0 — 2017-04-21
- 1.4.0 — 2016-09-02
- 1.3.0 — 2016-04-29
- 1.2.0 — 2016-03-15
- 1.1.4 — 2015-09-08
- 1.1.3 — 2015-09-08
- 1.1.1 — 2015-08-18
- 1.1.0 — 2015-07-22
- 1.0.2 — 2015-04-14
- 1.0.1 — 2015-04-14
- … 13 more at https://npm.io/package/handlebars-loader/versions

## README

[![latest version](https://img.shields.io/npm/v/handlebars-loader.svg?maxAge=2592000)](https://www.npmjs.com/package/handlebars-loader)
[![downloads](https://img.shields.io/npm/dm/handlebars-loader.svg?maxAge=2592000)](https://www.npmjs.com/package/handlebars-loader)
[![Build Status](https://github.com/pcardune/handlebars-loader/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/pcardune/handlebars-loader/actions/workflows/test.yml)
[![Coverage Status](https://coveralls.io/repos/github/pcardune/handlebars-loader/badge.svg?branch=main)](https://coveralls.io/github/pcardune/handlebars-loader?branch=main)
[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)

# handlebars-loader

A [handlebars](http://handlebarsjs.com) template loader for [webpack](https://github.com/webpack/webpack).

_Handlebars 4 now supported_

## Installation

`npm i handlebars-loader --save`

## General Usage

### webpack configuration

```javascript
{
  ...
  module: {
    rules: [
      ...
      { test: /\.handlebars$/, loader: "handlebars-loader" }
    ]
  }
}
```

### Your JS making use of the templates

```javascript
var template = require("./file.handlebars");
// => returns file.handlebars content as a template function
```

## Details

The loader resolves partials and helpers automatically. They are looked up relative to the current directory (this can be modified with the `rootRelative` option) or as a module if you prefix with `$`.

```handlebars
A file "/folder/file.handlebars".
{{> partial}} will reference "/folder/partial.handlebars".
{{> ../partial}} will reference "/partial.handlebars".
{{> $module/partial}} will reference "/folder/node_modules/module/partial.handlebars".
{{helper}} will reference the helper "/folder/helper.js" if this file exists.
{{[nested/helper] 'helper parameter'}} will reference the helper "/folder/nested/helper.js" if this file exists, passes 'helper parameter' as first parameter to helper.
{{../helper}} {{$module/helper}} are resolved similarly to partials.
```

The following query (or config) options are supported:

- _helperDirs_: Defines additional directories to be searched for helpers. Allows helpers to be defined in a directory and used globally without relative paths. You must surround helpers in subdirectories with brackets (Handlerbar helper identifiers can't have forward slashes without this). See [example](https://github.com/altano/handlebars-loader/tree/main/examples/helperDirs)
- _runtime_: Specify the path to the handlebars runtime library. Defaults to look under the local handlebars npm module, i.e. `handlebars/runtime`.
- _extensions_: Searches for templates with alternate extensions. Defaults are .handlebars, .hbs, and '' (no extension).
- _inlineRequires_: Defines a regex that identifies strings within helper/partial parameters that should be replaced by inline require statements. **Note**: For this to work, you'll have to disable the `esModule` Option in the corresponding file-loader entry in your webpack config.
- _rootRelative_: When automatically resolving partials and helpers, use an implied root path if none is present. Default = `./`. Setting this to be empty effectively turns off automatically resolving relative handlebars resources for items like `{{helper}}`. `{{./helper}}` will still resolve as expected.
- _knownHelpers_: Array of helpers that are registered at runtime and should not explicitly be required by webpack. This helps with interoperability for libraries like Thorax [helpers](http://thoraxjs.org/api.html#template-helpers).
- _exclude_: Defines a regex that will exclude paths from resolving. This can be used to prevent helpers from being resolved to modules in the `node_modules` directory.
- _debug_: Shows trace information to help debug issues (e.g. resolution of helpers).
- _partialDirs_: Defines additional directories to be searched for partials. Allows partials to be defined in a directory and used globally without relative paths. See [example](https://github.com/altano/handlebars-loader/tree/main/examples/partialDirs)
- _ignorePartials_: Prevents partial references from being fetched and bundled. Useful for manually loading partials at runtime.
- _ignoreHelpers_: Prevents helper references from being fetched and bundled. Useful for manually loading helpers at runtime.
- _precompileOptions_: Options passed to handlebars precompile. See the Handlebars.js [documentation](https://handlebarsjs.com/api-reference/compilation.html#handlebars-compile-template-options) for more information.
- _config_: Tells the loader where to look in the webpack config for configurations for this loader. Defaults to `handlebarsLoader`.
- _config.partialResolver_ You can specify a function to use for resolving partials. To do so, add to your webpack config:
  ```js
  handlebarsLoader: {
      partialResolver: function(partial, callback){
          // should pass the partial's path on disk
          // to the callback. Callback accepts (err, locationOnDisk)
      }
  }
  ```
- _config.helperResolver_ You can specify a function to use for resolving helpers. To do so, add to your webpack config:
  `js handlebarsLoader: { helperResolver: function(helper, callback){ // should pass the helper's path on disk // to the callback if one was found for the given parameter. // Callback accepts (err, locationOnDisk) // Otherwise just call the callback without any arguments } } `
  See [`webpack`](https://github.com/webpack/webpack) documentation for more information regarding loaders.

## Full examples

See the [examples](examples/) folder in this repo. The examples are fully runnable and demonstrate a number of concepts (using partials and helpers) -- just run `webpack` in that directory to produce `dist/bundle.js` in the same folder, open index.html.

## Change Log

See the [CHANGELOG.md](https://github.com/pcardune/handlebars-loader/blob/main/CHANGELOG.md) file.

## License

MIT (http://www.opensource.org/licenses/mit-license)

---
_Source: https://npm.io/package/handlebars-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._