gulp-handlebars

Handlebars plugin for gulp 3

Usage

First, install gulp-handlebars and gulp-define-module as development dependencies:

npm install --save-dev gulp-handlebars gulp-define-module

Template modules for Node.js

This example will make templates available for loading via Node's require:

var handlebars = require('gulp-handlebars');
var defineModule = require('gulp-define-module');

gulp.task('templates', function(){
  gulp.src(['templates/*.hbs'])
    .pipe(handlebars())
    .pipe(defineModule('node'))
    .pipe(gulp.dest('build/templates/'));
});

Templates can then be used within Node as such:

var appTemplate = require('./build/templates/App.Header.js');
var html = appTemplate(data);

Namespaced templates for the browser

gulp-declare can be used to safely declare template namespaces and make templates available for use in the browser:

var handlebars = require('gulp-handlebars');
var defineModule = require('gulp-define-module');
var declare = require('gulp-declare');
var concat = require('gulp-concat');

gulp.task('templates', function(){
  gulp.src(['client/templates/*.hbs'])
    .pipe(handlebars())
    .pipe(defineModule('plain'))
    .pipe(declare({
      namespace: 'MyApp.templates'
    }))
    .pipe(concat('templates.js'))
    .pipe(gulp.dest('build/js/'));
});

The templates path within the namespace is the base namespace combined with the template's filename. For a template named App.Header.hbs with a namespace of MyApp.Templates, the compiled template would be available as MyApp.Templates.App.Header.

The resulting templates.js would look like:

this["MyApp"] = this["MyApp"] || {};
this["MyApp"]["templates"] = this["MyApp"]["templates"] || {};
this["MyApp"]["templates"]["App"] = this["MyApp"]["templates"]["App"] || {};
this["MyApp"]["templates"]["App"]["Header"] = Handlebars.template(function() { /* compiled template function */ });

gulp-define-module can also be used to assign templates as properties of an already declared namespace:

var handlebars = require('gulp-handlebars');
var defineModule = require('gulp-define-module');
var concat = require('gulp-concat');

gulp.task('templates', function(){
  gulp.src(['client/templates/*.hbs'])
    .pipe(handlebars())
    .pipe(defineModule('plain', {
      // Assumes MyApp.Templates is already declared
      wrapper: 'MyApp.templates["<%= name %>"] = <%= handlebars %>'
    }))
    .pipe(concat('templates.js'))
    .pipe(gulp.dest('build/js/'));
});

For a template named App.Header.hbs, the resulting templates.js would look like:

MyApp.templates["App.Header"] = Handlebars.template(function() { /* compiled template function */ };

The gulp-define-module method above assumes the following:

MyApp.templates will be defined before the templates.js script is included for use in the browser
Templates with dots in their names will be assigned as MyApp.Templates["App.Header"], not MyApp.Templates.App.Header
The template name does not contain double quotes

See the gulp-define-module documentation for more details.

Compiling to various module systems

See the gulp-define-module documentation for details on how to define templates as AMD, Node, CommonJS, and hybrid modules.

gulp-handlebars makes the following available for use in gulp-define-module's wrapper template option:

<%= handlebars %> - The Handlebars template, wrapped in a call to Handlebars.template()
<%= contents %> - The bare Handlebars template (not wrapped).

gulp-handlebars also sets a default require of { Handlebars: 'handlebars' } for gulp-define-module so Handlebars will be present in when defining AMD, Node, CommonJS, or hybrid modules.

API

handlebars(options)

options.compilerOptions

Type: Object

Compiler options to pass to Handlebars.precompile().

mkleehammer / gulp-handlebars