gulp-underscore-template

1.0.0 verified Fri May 01 auth: no javascript deprecated

Gulp plugin that compiles Underscore template (`.html`) files into a single CommonJS module. Version 1.0.0 (latest, 2014) – no updates since. Differentiates by providing a Gulp-stream-friendly API for precompiling templates, enabling minification before compilation, and outputting a require-able module. Alternatives exist in more maintained gulp- template plugins (e.g., gulp-template-compile).

Common errors

error TypeError: _.template is not a function ↓

cause Missing underscore peer dependency or version mismatch.

fix

Install underscore: npm install underscore --save (must be a runtime dependency in consuming project).

error Cannot find module 'gulp-underscore-template' ↓

cause Package not installed.

fix

Run: npm install gulp-underscore-template --save-dev (requires gulp as well).

error SyntaxError: Unexpected token import ↓

cause Output file uses CommonJS; importing it via ESM without transpilation fails.

fix

Use require() or transpile the output file with Babel/TypeScript.

Warnings

deprecated Package has not been updated since 2014 and is effectively unmaintained. ↓

fix Consider using actively maintained alternatives like gulp-template-compile or gulp-angular-templatecache for newer projects.

gotcha Template filenames are used as keys with extension removed; hyphens are preserved, requiring bracket notation for access. ↓

fix Use bracket notation: templates['file-name'] instead of templates.fileName.

gotcha Output module uses CommonJS `module.exports`, so ESM consumers need a default import interop or enable esModuleInterop. ↓

fix In TypeScript, set esModuleInterop: true; otherwise use `const templates = require(...)`.

gotcha Plugin does not minify HTML; user must pipe through htmlmin separately. ↓

fix Add .pipe(htmlmin({...})) before .pipe(template()).

Install

npm install gulp-underscore-template

yarn add gulp-underscore-template

pnpm add gulp-underscore-template

Imports

default
wrong
```
const template = require('gulp-underscore-template');
```
correct
```
import template from 'gulp-underscore-template'
```
ESM default import; CommonJS require also works with default export. Plugin is a function.
require('./lib/templates')
wrong
```
import templates from './lib/templates'
```
correct
```
const templates = require('./lib/templates');
```
Output module uses CommonJS; ESM import requires default interop (module has no default export).
templates['some-page']
wrong
```
const tpl = templates.somePage;
```
correct
```
const tpl = templates['some-page'];
```
Template keys match filenames (with extension removed), but hyphens require bracket notation.

Quickstart

Compiles all HTML templates into a single CommonJS module using gulp pipeline.

var gulp = require('gulp');
var concat = require('gulp-concat');
var htmlmin = require('gulp-htmlmin');
var template = require('gulp-underscore-template');

gulp.task('templates', function() {
  return gulp.src('./templates/*.html')
    .pipe(htmlmin({ collapseWhitespace: true, conservativeCollapse: true }))
    .pipe(template())
    .pipe(concat('templates.js'))
    .pipe(gulp.dest('./lib/'));
});