Gulp Build for Handlebars Templating

0.5.3 · abandoned · verified Tue Apr 21

The package `gulp-build` (version 0.5.3) is a Gulp 3 plugin designed to process files by swapping in variables using Handlebars templates. It facilitates building files for different environments by dynamically injecting data like Google Analytics IDs or compiling static HTML. Key features include support for Handlebars helpers, partials, and layouts, which were introduced in version 0.5.0, replacing earlier Underscore template integration. The plugin's current version (0.5.3) dates back to 2014 based on the copyright notice in its README, suggesting a lack of recent development. Its release cadence is effectively halted. It differentiates itself by providing a simple Handlebars-based templating pipeline within a Gulp 3 workflow, though a noted limitation is that partials and layouts must be provided as raw strings rather than file globs. Given its age and the fact that Gulp itself has advanced significantly beyond version 3, this package is effectively abandoned and may not be compatible with modern Gulp setups.

Common errors

```
Compiled file is missing the main content or appears empty.
```
cause The layout string passed to `gulp-build` does not contain the mandatory `{{> body}}` tag.

fix Edit your `config.layout` string to include `{{> body}}` at the position where the main file content should be rendered.
```
TypeError: Cannot read properties of undefined (reading 'registerHelper') or similar Handlebars errors.
```
cause Attempting to use `gulp-build` with templates written in Underscore.js syntax after upgrading to version 0.5.0 or later, which switched to Handlebars.

fix Rewrite your templates from Underscore.js syntax to Handlebars syntax. Ensure all helpers, partials, and data references conform to Handlebars specifications.

Warnings

breaking Version 0.5.0 introduced a significant breaking change by migrating the templating engine from Underscore templates to Handlebars. Projects upgrading from versions prior to 0.5.0 will need to rewrite their templates to conform to Handlebars syntax.
Fix: Rewrite all existing Underscore templates to Handlebars syntax. Consult Handlebars documentation for syntax and helper migration.
gotcha When using layouts, the `{{> body}}` Handlebars partial is mandatory within your layout string. Omitting this tag will result in the main content of your source files not being injected into the layout, leading to empty or incomplete output files.
Fix: Ensure your `config.layout` string explicitly includes `{{> body}}` where you want the main content to be inserted.
gotcha The `partials` and `layout` options only accept strings for their template definitions. There is no built-in support for globbing file paths for partials or layouts, meaning all template content must be provided inline or read into strings programmatically.
Fix: Manually read partial and layout files into strings before passing them to the `gulp-build` options. For example, use `fs.readFileSync` to load templates.
deprecated This package is designed for Gulp 3 and has not been updated since 2014 (version 0.5.3). It is effectively abandoned and may not be compatible with newer versions of Node.js or Gulp (Gulp 4+). Consider using more modern templating solutions or Gulp plugins.
Fix: Evaluate alternative, actively maintained templating plugins for Gulp or migrate to a different build system if Gulp 3 compatibility is not critical.

Install

npm install gulp-build npm
yarn add gulp-build yarn
pnpm add gulp-build pnpm

Imports

build
wrong:
```
import build from 'gulp-build';
```
correct:
```
const build = require('gulp-build');
```
This package is a CommonJS module and does not support ES modules directly. It is designed for Gulp 3, which often used CommonJS.

Quickstart

Demonstrates basic usage of `gulp-build` to process HTML files using Handlebars with dynamic data, partials, and a layout.

const gulp = require('gulp');
const build = require('gulp-build');
const path = require('path');

// Pre-requisites:
// 1. Create a 'src' directory in your project root.
// 2. Inside 'src', create 'index.html' with content like: <h1>Hello, {{title}}!</h1>\n{{> footer}}
// 3. Run `npm install --save-dev gulp gulp-build`

const buildOptions = {
  partials: [{
    name: 'footer',
    tpl: '<p>Copyright 2013 by My Company</p>'
  }],
  layout: '<html><head><title>{{title}}</title></head><body>\n{{> body}}\n</body></html>'
};

gulp.task('build-html', function() {
  // Processes HTML files from the 'src' directory
  // and outputs them to a 'dist' directory.
  return gulp.src(path.join(__dirname, 'src', '*.html'))
      .pipe(build({ title: 'My Awesome Website' }, buildOptions))
      .pipe(gulp.dest(path.join(__dirname, 'dist')));
});

// To run this task, execute `gulp build-html` in your terminal.

view raw JSON →