Skip to content


Subversion checkout URL

You can clone with
Download ZIP
grunt plugin to compile static html from a handlebars plugin
JavaScript HTML
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

grunt-compile-handlebars Build Status

Compiles handlebar templates, outputs static HTML

Getting Started

Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-compile-handlebars

Then add this line to your project's Gruntfile.js gruntfile:




patrick kettner - a web developer who consistently worked with large static data sets.


grunt-compile-handlebars takes in a handlebars tempalte (and optionally static pre and post html), runs a dataset over it, and outputs static html.


inside of a grunt task. I assume you know what gruntjs is, but if not -


You have ton of data that rarely changes that you want to template.


There are a lot of different ways to input data, it accepts most any dynamic and static input. Heres a few of the ways you can use it

'compile-handlebars': {
    allStatic: {
      preHTML: 'test/fixtures/pre-dev.html',
      postHTML: 'test/fixtures/post-dev.html',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/allStatic.html'
    dynamicTemplate: {
      template: '<h1>{{salutation}}{{punctuation}} {{location}}</h1>',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicTemplate.html'
    dynamicTemplateData: {
      template: 'test/fixtures/template.handlebars',
      templateData: {
          "salutation": "Hallo",
          "punctuation": ",",
          "location": "Welt"
      output: 'tmp/dynamicTemplateData.html'
    dynamicPre: {
      preHTML: '<header>INLINE HEADER</header>',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicPre.html'
    dynamicPost: {
      postHTML: '<footer>INLINE HEADER</footer>',
      template: 'test/fixtures/template.handlebars',
      templateData: 'test/fixtures/data.json',
      output: 'tmp/dynamicPost.html'
    allArray: {
      template: ['test/fixtures/deep/spanish.handlebars', 'test/fixtures/deep/deeper/portuguese.handlebars'],
      templateData: ['test/fixtures/deep/spanish.handlebars', 'test/fixtures/deep/deeper/portuguese.json'],
      output: ['tmp/deep/spanish.html','tmp/deep/deeper/portuguese.html'],
      helpers: ['test/helpers/super_helper.js'],
      partials: ['test/fixtures/deep/shared/foo.handlebars']
    globbedTemplateAndOutput: {
      template: 'test/fixtures/deep/**/*.handlebars',
      templateData: 'test/fixtures/deep/**/*.json',
      output: 'tmp/deep/**/*.html'
    globalJsonGlobbedTemplate: {
      template: 'test/fixtures/deep/**/*.handlebars',
      templateData: 'test/fixtures/deep/**/*.json',
      output: 'tmp/deep/**/*.html',
      helpers: 'test/helpers/**/*.js',
      partials: 'test/fixtures/deep/shared/**/*.handlebars',
      globals: [

The available configuration options are as follows

Unless otherwise noted, all configurable values can be represented as

  • a string representing the path to a specific file
  • a string representing the path to a globbed representation of the files, matched up against the values resolved from the template configuration
  • an array of literal paths, globbed paths, or a combination of the two

template - The template fed to handlebars. In addition to the normal configurable values, it can also be an inline string representation of a template (e.g. raw html and handlebars).

preHTML - Static text to be inserted before the compiled template postHTML - Static text to be inserted after the compiled template

__templateData ~~ The data being fed to compiled template, in addition to the normal configurable values, this can be

  • an inline string representation of a data (I don't know why you would do that though, when you can do...)
  • an inline JSON representation of a data

output - the file(s) that handlebars saves the files to. This can be globals - globals that can be included, useful for when you have template specific data, but want some data available to all templates helpers - handlebars helpers partials - handlebars partials

registerFullPath - normally, helpers and partials are registered under their basename, rather than their path (e.g. partial at partials/deep/awesomePartial.handlebars is registered as {{> awesomePartial}}). When set to true, helpers and partials are registered under their full paths (e.g. {{> partials/deep/awesomePartial}}), to prevent clobbering after resolving globbed values.

A note on globing

When you specify templates using globs, the values from template are used to create the values for output, for example, if your file structure looks like this


and your configuration looks like this

  "template": "./foo/*.handlebars",
  "templateData": "./foo/*.json",
  "output":  "./foo/*.html"

the output would be ./foo/bar.html and ./foo/baz.html


I had to work with several hundred repeated data structures that never changed. Keeping them all in html was silly, but pushing out a template engine for the end user to compile the same information multiple times was even sillier. This allows you to have your templated cake and eat it too.

Release History

  • 0.7.6 - Kristofferson - explicitly check that isGlob is undefined, preventing a false negative on empty strings
  • 0.7.5 - Redford - add registerFullPath option to prevent partial/helper registration clobbering, update README
  • 0.7.4 - M. Jean - don't send objects to handlebars.compile, code cleanup
  • 0.7.3 - Cousin Ben - switch from require to readFile to allow for html in partials
  • 0.7.2 - Bernice - @stimmins improved handling of templateData and globals
  • 0.7.1 - Margaret - fix 0.8 compatibility
  • 0.7.0 - Rosemary - Allow for arrays instead of globbing, remove depreicated grunt methods
  • 0.6.3 - Pelé - @mattcg fixed an issue with large amounts of templates
  • 0.6.2 - Dignan - @goette added support for a global json config
  • 0.6.1 - Grace - @robinqu added support for handlebars partials
  • 0.6.0 - Future Man - added globbing, lots more test
  • 0.4.0 - Oseary - upgraded to grunt 0.4, removed extra tasks, added tests
  • 0.0.2 - Inez - changed to grunt's native json parser (thanks to @sebslomski). Updated Readme
  • 0.0.1 - Dudley - Initial commit


Copyright (c) 2014 Patrick Kettner Licensed under the MIT license.

Something went wrong with that request. Please try again.