mustache-loader

1.4.3 verified Sat Apr 25 auth: no javascript

A webpack loader that compiles Mustache templates using Hogan.js. Current stable version is 1.4.3, with last release in 2016. It has peer dependencies on hogan.js and webpack (supports webpack 1.x, 2.x, and 4.x beta). Supports options like minification via html-minifier, tiny output, client-side compilation, and direct rendering. Differentiators include optional noShortcut for partials and render function for hot reloading. It is a straightforward conversion from Mustache templates to JavaScript functions, with minimal overhead.

Common errors

error Module build failed: TypeError: Cannot read property 'render' of undefined ↓

cause Using template.render() without the 'noShortcut' option (template is already rendered HTML string).

fix

Call template({}) directly instead of template.render({}). If you need partials, add '?noShortcut' to the loader.

error Module not found: Error: Can't resolve 'hogan.js' ↓

cause hogan.js is a peer dependency not installed automatically.

fix

Run: npm install hogan.js

error Invalid options object. Mustache Loader has been initialized using an options object that does not match the API schema. ↓

cause Using an options object with invalid keys or format (e.g., webpack 2+ query syntax change).

fix

Use query string format e.g., 'mustache-loader?minify' or options object with only allowed keys: minify, noShortcut, clientSide, tiny, render.

Warnings

breaking Webpack 1.x uses 'loaders' array with 'loader' property; webpack 2+ uses 'rules' with 'use' property. ↓

fix Use module.rules array with use property for webpack 2+.

deprecated Peer dependency webpack "*" allows any version, but breaking changes exist across major versions. ↓

fix Specify exact webpack version range in your project.

gotcha If another loader is chained after mustache-loader, minify, clientSide, and tiny options are ignored. ↓

fix Ensure mustache-loader is the last loader in the chain for those options to work.

gotcha The 'tiny' option will not emit the template source, which may break HtmlWebpackPlugin if used without 'render'. ↓

fix Use 'render' option when using 'tiny' with HtmlWebpackPlugin.

gotcha When using 'render' as a function, ensure it returns an object synchronously; otherwise rendering may fail. ↓

fix Use a synchronous function or wrap in a data property.

Install

npm install mustache-loader

yarn add mustache-loader

pnpm add mustache-loader

Imports

default (template function)
wrong
```
import { template } from './file.html';
```
correct
```
import template from './file.html';
```
The loader exports the compiled template as a function by default. Named import will not work.

require (CommonJS)

wrong

const { template } = require('./file.html');

correct

const template = require('./file.html');

CommonJS returns the function directly, not an object.

Hogan template object (with noShortcut)
```
const template = require('./file.html'); const html = template.render({foo: 'bar'});
```
When using noShortcut option, the returned value is a Hogan template object with a render method.

Quickstart

Shows basic webpack configuration to use mustache-loader and how to import and use a compiled template.

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

// app.js
import template from './template.html';
const html = template({ name: 'World' });
console.log(html);