pug-loader

2.4.0 verified Sat Apr 25 auth: no javascript

Webpack loader for Pug (formerly Jade) templates, version 2.4.0. Compiles Pug templates to JavaScript template functions at build time. Works with webpack module bundler, supports embedded resources via require(), and can render HTML at compile time using apply-loader. Supports both .pug and legacy .jade files. Options map directly to Pug options. Requires pug ^2.0.0 as a peer dependency. A key differentiator is automatic resolution of includes and inheritance via webpack's module resolution.

Common errors

error Module not found: Error: Cannot resolve 'file' or 'directory' ./file.pug ↓

cause Missing or misconfigured loader binding for .pug extension.

fix

Add a rule in webpack.config.js: { test: /\.pug$/, loader: 'pug-loader' }

error TypeError: pug.compile is not a function ↓

cause Incorrect version of pug (v1.x) installed. pug-loader requires pug ^2.0.0.

fix

Install pug v2: npm install pug@2

error Error: options.plugins contains a plugin that implements 'read' or 'resolve'. These hooks are reserved for the loader. ↓

cause Using a Pug plugin that implements file reading/resolution which conflicts with webpack.

fix

Remove the plugin or use webpack aliases/resolve for file resolution.

Warnings

breaking webpack 2+ changed from module.loaders to module.rules. Using module.loaders will not work. ↓

fix Replace module.loaders array with module.rules in your webpack config.

deprecated Inline loader syntax (e.g., require('pug-loader!./file.pug')) is discouraged in webpack 2+. ↓

fix Bind pug-loader to .pug files via module.rules and use plain require('./file.pug').

gotcha Pug plugins implementing 'read' or 'resolve' hooks are not supported due to webpack's file resolution. ↓

fix Avoid using such plugins or implement custom resolution via webpack aliases.

gotcha If your .pug files include other .pug files, you must bind pug-loader to .pug extension, else includes will fail. ↓

fix Ensure module.rules includes test: /\.pug$/ for pug-loader.

deprecated Legacy .jade extension support may be removed in future versions. ↓

fix Rename .jade files to .pug and update references.

Install

npm install pug-loader

yarn add pug-loader

pnpm add pug-loader

Imports

pug-loader

wrong

module.exports = { ... config: { module: { loaders: [ { test: /\.pug$/, loader: 'pug-loader' } ] } } }

correct

module.exports = { ... config: { module: { rules: [ { test: /\.pug$/, loader: 'pug-loader' } ] } } }

Since webpack 2, use 'rules' not 'loaders' in module configuration.

template function

wrong

var template = require('./file.pug'); (without binding loader)

correct

var template = require('pug-loader!./file.pug');

Inline loader syntax ensures pug-loader is used even if not bound to .pug extension.

apply-loader

wrong

var html = require('!pug-loader!./file.pug'); (missing apply-loader)

correct

var html = require('apply-loader!pug-loader!./file.pug');

Use apply-loader to get rendered HTML at compile time instead of template function.

Quickstart

Shows webpack configuration for pug-loader and usage in JavaScript to compile a Pug template with locals.

// webpack.config.js
module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  },
  module: {
    rules: [
      {
        test: /\.pug$/,
        loader: 'pug-loader',
        options: {
          doctype: 'html',
          pretty: true
        }
      }
    ]
  }
};

// src/index.js
var template = require('./template.pug');
var html = template({ name: 'World' });
console.log(html);