Underscore Template Loader

1.2.0 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that compiles Underscore.js or Lodash templates. Current stable version 1.2.0 supports Webpack 5. Low maintenance, no recent releases since 2021. Supports macros, template settings (interpolate/evaluate/escape), imports, and prepending filename comments for debugging. Works with file-loader and url-loader for image references. Key differentiator: enables using _.template and lodash templates as Webpack modules with additional macro features like @include and @require.

Common errors

error Module not found: Error: Can't resolve 'underscore-template-loader' ↓

cause Loader not installed or not listed in webpack config correctly.

fix

Run npm install underscore-template-loader --save-dev and ensure loader: 'underscore-template-loader' in webpack config.

error You may need an appropriate loader to handle this file type. ↓

cause Webpack doesn't have rule for .html files to use underscore-template-loader.

fix

Add { test: /\.html$/, loader: 'underscore-template-loader' } to webpack module.rules.

error Cannot find module 'underscore' ↓

cause underscore package not installed, but required by compiled template at runtime.

fix

Install underscore: npm install underscore (or lodash if using lodash engine).

Warnings

gotcha When using lodash, template imports require setting _.templateSettings.imports before requiring the template. ↓

fix Set _.templateSettings.imports before any require/import calls to the loader.

breaking Webpack 4 changed loader configuration from `loaders` (array of objects) to `rules` (array with `use` or `loader`). ↓

fix Use `module.rules` instead of `module.loaders`. Example is for old syntax.

deprecated The `include` tag is deprecated in favor of `@include` and `@require` macros. ↓

fix Use `@include` or `@require` macros instead.

gotcha Images in templates require file-loader or url-loader to be installed and configured separately. ↓

fix Add appropriate loader rule for image file types.

breaking Webpack 5 may require adjustments to loader query options; version 1.2 adds support. ↓

fix Ensure you use underscore-template-loader 1.2.0 or later for Webpack 5 compatibility.

Install

npm install underscore-template-loader

yarn add underscore-template-loader

pnpm add underscore-template-loader

Imports

underscore
wrong
```
const _ = require('underscore');
```
correct
```
import _ from 'underscore'
```
CommonJS require also works but is outdated for modern ESM projects.
lodash
wrong
```
const _ = require('lodash');
```
correct
```
import _ from 'lodash'
```
lodash can be used as engine; similar to underscore.
compiled template
wrong
```
const tmpl = require('./template.html');
```
correct
```
import tmpl from './template.html'
```
Loader returns a function; use default import for ESM.

Quickstart

Shows basic webpack rule, template usage, and import of compiled template as a function.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      { test: /\.html$/, loader: 'underscore-template-loader' },
    ],
  },
};

// template.html
<p>Hello <%= name %></p>

// app.js
import tmpl from './template.html';
const result = tmpl({ name: 'world' });
console.log(result); // <p>Hello world</p>