handlebars-loader

What is handlebars-loader?

The handlebars-loader package is a webpack loader that allows you to precompile Handlebars templates. It integrates Handlebars with your webpack build process, enabling you to use Handlebars templates in your JavaScript applications seamlessly.

What are handlebars-loader's main functionalities?

Basic Template Loading

This feature allows you to load Handlebars templates using the handlebars-loader. The code sample shows a basic webpack configuration that uses handlebars-loader to process files with the .hbs extension.

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/,
        loader: 'handlebars-loader'
      }
    ]
  }
};

Precompile Templates

This feature allows you to precompile Handlebars templates and use them in your JavaScript code. The code sample demonstrates how to require a Handlebars template, pass a context object to it, and generate HTML.

const template = require('./template.hbs');
const context = { title: 'My New Post', body: 'This is my first post!' };
const html = template(context);
console.log(html);

Custom Helper Registration

This feature allows you to register custom Handlebars helpers. The code sample shows how to configure handlebars-loader to look for custom helpers in a specified directory.

module.exports = {
  module: {
    rules: [
      {
        test: /\.hbs$/,
        loader: 'handlebars-loader',
        options: {
          helperDirs: [path.resolve(__dirname, 'helpers')]
        }
      }
    ]
  }
};

Other packages similar to handlebars-loader

html-loader

The html-loader package is a webpack loader that exports HTML as a string. It can be used to load HTML files and process them with webpack. Unlike handlebars-loader, it does not support Handlebars templating but is useful for loading static HTML files.

ejs-loader

The ejs-loader package is a webpack loader for EJS templates. It allows you to precompile EJS templates and use them in your JavaScript applications. While similar in purpose to handlebars-loader, it uses EJS instead of Handlebars for templating.

pug-loader

The pug-loader package is a webpack loader for Pug templates (formerly known as Jade). It enables you to precompile Pug templates and use them in your JavaScript code. Like handlebars-loader, it integrates a templating engine with webpack, but it uses Pug instead of Handlebars.

README

handlebars-loader

A handlebars template loader for webpack.

Handlebars 4 now supported

Installation

npm i handlebars-loader --save

General Usage

webpack configuration

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

Your JS making use of the templates

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 $.

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
• 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.
• 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
• 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 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:

  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 documentation for more information regarding loaders.

Full examples

See the 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 file.

License

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