# gulp-hb

> A sane Handlebars Gulp plugin.

Latest version **8.0.0** (published 2019-02-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-hb
pnpm add gulp-hb
yarn add gulp-hb
bun add gulp-hb
```

## 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 | 8.0.0 |
| Published | 2019-02-19 |
| First published | 2014-05-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 4 |
| Dependencies | 7 |
| Unpacked size | 19.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 147 |
| Author | Shannon Moeller |
| Maintainers | shannonmoeller |
| Keywords | gulpplugin, gulp, handlebars, hb, hbs, hbt, compile, render, static, data, partial, partials, helper, helpers, decorator, decorators |

## Links

- npm: https://www.npmjs.com/package/gulp-hb
- Repository: https://github.com/shannonmoeller/gulp-hb
- Issues: https://github.com/shannonmoeller/gulp-hb/issues
- npm.io page: https://npm.io/package/gulp-hb

## Dependencies (7)

- [through2](https://npm.io/package/through2.md) ^3.0.0
- [ansi-gray](https://npm.io/package/ansi-gray.md) ^0.1.1
- [ansi-green](https://npm.io/package/ansi-green.md) ^0.1.1
- [handlebars](https://npm.io/package/handlebars.md) ^4.1.0
- [cli-columns](https://npm.io/package/cli-columns.md) ^3.1.2
- [plugin-error](https://npm.io/package/plugin-error.md) ^1.0.1
- [handlebars-wax](https://npm.io/package/handlebars-wax.md) ^6.1.0

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 8.0.0 (latest) — 2019-02-19
- 7.1.0 — 2019-02-19
- 7.0.1 — 2018-01-03
- 7.0.0 — 2017-12-31
- 6.0.2 — 2017-01-26
- 6.0.1 — 2017-01-26
- 6.0.0 — 2017-01-26
- 5.1.4 — 2016-09-26
- 5.1.3 — 2016-09-26
- 5.1.2 — 2016-09-20
- 5.1.1 — 2016-09-20
- 5.1.0 — 2016-04-20
- 5.0.1 — 2016-03-09
- 5.0.0 — 2016-03-09
- 4.0.3 — 2016-02-19
- … 36 more at https://npm.io/package/gulp-hb/versions

## README

# `gulp-hb`

[![NPM version][npm-img]][npm-url] [![Downloads][downloads-img]][npm-url] [![Build Status][travis-img]][travis-url] [![Coverage Status][coveralls-img]][coveralls-url] [![Tip][amazon-img]][amazon-url]

A sane static [Handlebars][handlebars] Gulp plugin. Useful as a static site generator. Powered by [`handlebars-wax`][wax]. Think [Assemble][assemble], but with a lot less [Jekyll][jekyll] baggage.

To precompile templates into JavaScript, see [`gulp-handlebars`][gulp-handlebars].

## Install

```console
$ npm install --save-dev gulp-hb
```

## Usage

```js
const gulp = require('gulp');
const hb = require('gulp-hb');

// Basic

function basic() {
    return gulp
        .src('./src/{,posts/}*.html')
        .pipe(hb()
            .partials('./src/assets/partials/**/*.hbs')
            .helpers('./src/assets/helpers/*.js')
            .data('./src/assets/data/**/*.{js,json}')
        )
        .pipe(gulp.dest('./web'));
}

gulp.task('basic', basic);

// Advanced

function advanced() {
    const hbStream = hb({ debug: true })
        // Partials
        .partials('./partials/components/**/*.{hbs,js}')
        .partials('./partials/layouts/**/*.{hbs,js}')
        .partials({
            boo: '{{#each boo}}{{greet}}{{/each}}',
            far: '{{#each far}}{{length}}{{/each}}'
        })

        // Helpers
        .helpers(require('handlebars-layouts'))
        .helpers('./helpers/**/*.js')
        .helpers({
            foo: function () { ... },
            bar: function () { ... }
        })

        // Decorators
        .decorators('./decorators/**/*.js')
        .decorators({
            baz: function () { ... },
            qux: function () { ... }
        })

        // Data
        .data('./data/**/*.{js,json}')
        .data({
            lorem: 'dolor',
            ipsum: 'sit amet'
        });

    return gulp
        .src('./src/{,posts/}*.html')
        .pipe(hbStream)
        .pipe(gulp.dest('./web'));
}

gulp.task('advanced', advanced);
```

### Template Context

The template context is a merge of pre-registered data and file-specific data. Pre-registered data is available to all templates and is set using the `.data()` method. File-specific data is available to the current template and is set via the [`file.data`](#file-specific-data-sources) property.

#### `@` Data Variables

##### @root

The merged object of pre-registered data and file-specific data is available as the primary context of your templates. In cases where accessing this data would require the use of `../`, you may access the top-level context via `@root`:

```handlebars
{{ foo }}
{{ @root.foo }}

{{#each bar}}
    {{ ../foo }}
    {{ @root.foo }}
{{/each}}
```

##### @global

In cases where file-specific data keys collide with pre-registered data keys, you may access the pre-registered data via `@global`:

```handlebars
{{ @global.foo }}
```

##### @local

In cases where pre-registered data should be ignored, you may access the file-specific data via `@local`.

```handlebars
{{ @local.foo }}
```

##### @file

In cases where information about the template file itself is needed, you may access the [file object][file] via `@file`:

```handlebars
{{ @file.path }}
```

#### File-specific Data Sources

File-specific data is set via the `file.data` property using other plugins such as [`gulp-data`][gulp-data], [`gulp-data-json`][gulp-data-json], or [`gulp-front-matter`][gulp-front-matter].

```js
const gulp = require('gulp');
const data = require('gulp-data');
const frontMatter = require('gulp-front-matter');
const hb = require('gulp-hb');

function inject() {
    return gulp
        .src('./src/*.html')

        // Load an associated JSON file per post.
        .pipe(data((file) => {
            return require(file.path.replace('.html', '.json'));
        }))

        // Parse front matter from post file.
        .pipe(frontMatter({
            property: 'data.frontMatter'
        }))

        // Data for everyone.
        .pipe(hb().data('./data/**/*.js'))

        .pipe(gulp.dest('./web'));
}

gulp.task('inject', inject);
```

#### Multiple Data Sources

Multiple data sources can be used to render the same set of templates to different directories using [`through2`][through2].

```js
const gulp = require('gulp');
const hb = require('gulp-hb');
const through = require('through2');

function i18n() {
    return gulp
        .src('./i18n/*.json')
        .pipe(through.obj((file, enc, cb) => {
            const locale = file.stem;
            const data = {
                locale: locale,
                i18n: JSON.parse(file.contents.toString())
            };

            gulp
                .src('./templates/**/*.html')
                .pipe(hb().data(data))
                .pipe(gulp.dest('./dist/' + locale))
                .on('error', cb)
                .on('end', cb);
        }));
}

gulp.task('i18n', i18n);
```

## API

### `hb([options]): TransformStream`

- `options` `{Object}` (optional) Passed directly to [`handlebars-wax`][wax] so check there for more options.
  - `bustCache` `{Boolean}` (default: `true`) Force reload data, partials, helpers, and decorators.
  - `cwd` `{String}` (default: `process.cwd()`) Current working directory.
  - `debug` `{Boolean|Number}` (default: `false` or `0`) Whether to log registered functions and data (`true` or `1`) and glob parsing (`2`).
  - `handlebars` `{Handlebars}` (optional) A specific instance of Handlebars, if needed.
  - `compileOptions` `{Object}` Options to use when compiling templates.
  - `templateOptions` `{Object}` Options to use when rendering templates.
  - `partials` `{String|Array.<String>|Object|Function(handlebars)}`
  - `parsePartialName` `{Function(options, file): String}`
  - `helpers` `{String|Array.<String>|Object|Function(handlebars)}`
  - `parseHelperName` `{Function(options, file): String}`
  - `decorators` `{String|Array.<String>|Object|Function(handlebars)}`
  - `parseDecoratorName` `{Function(options, file): String}`
  - `data` `{String|Array.<String>|Object}`
  - `parseDataName` `{Function(options, file): String}`

Returns a Gulp-compatible transform stream that compiles [Handlebars][handlebars] templates to static output.

### .partials(pattern [, options]): TransformStream

- `pattern` `{String|Array<String>|Object|Function(handlebars)}`
- `options` `{Object}` Same options as `hb()`.

Loads additional partials. See [`handlebars-wax`][wax].

### .helpers(pattern [, options]): TransformStream

- `pattern` `{String|Array<String>|Object|Function(handlebars)}`
- `options` `{Object}` Same options as `hb()`.

Loads additional helpers. See [`handlebars-wax`][wax].

### .decorators(pattern [, options]): TransformStream

- `pattern` `{String|Array<String>|Object|Function(handlebars)}`
- `options` `{Object}` Same options as `hb()`.

Loads additional decorators. See [`handlebars-wax`][wax].

### .data(pattern [, options]): TransformStream

- `pattern` `{String|Array<String>|Object}`
- `options` `{Object}` Same options as `hb()`.

Loads additional data. See [`handlebars-wax`][wax].

## Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

### Test

```console
$ npm test
```

----

MIT © [Shannon Moeller](http://shannonmoeller.com)

[assemble]: http://assemble.io/
[context]: https://github.com/shannonmoeller/handlebars-wax#context-and-rendering
[file]: https://github.com/gulpjs/vinyl#file
[gulp-data]: https://github.com/colynb/gulp-data#usage
[gulp-data-json]: https://github.com/kflorence/gulp-data-json#example
[gulp-front-matter]: https://github.com/lmtm/gulp-front-matter#usage
[gulp-handlebars]: https://github.com/lazd/gulp-handlebars#usage
[handlebars]: https://github.com/wycats/handlebars.js#usage
[jekyll]: https://jekyllrb.com/
[through2]: https://github.com/rvagg/through2#api
[wax]: https://github.com/shannonmoeller/handlebars-wax#usage

[amazon-img]:    https://img.shields.io/badge/amazon-tip_jar-yellow.svg?style=flat-square
[amazon-url]:    https://www.amazon.com/gp/registry/wishlist/1VQM9ID04YPC5?sort=universal-price
[coveralls-img]: http://img.shields.io/coveralls/shannonmoeller/gulp-hb/master.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/shannonmoeller/gulp-hb
[downloads-img]: http://img.shields.io/npm/dm/gulp-hb.svg?style=flat-square
[npm-img]:       http://img.shields.io/npm/v/gulp-hb.svg?style=flat-square
[npm-url]:       https://npmjs.org/package/gulp-hb
[travis-img]:    http://img.shields.io/travis/shannonmoeller/gulp-hb/master.svg?style=flat-square
[travis-url]:    https://travis-ci.org/shannonmoeller/gulp-hb

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