@webdiscus/pug-loader
Advanced tools
The pug loader for webpack resolves paths and webpack aliases in the pug template and compiles it to HTML.
Webpack loader for the Pug templates.
The pug-loader resolve paths and webpack aliases for extends/include/require() in pug template and compiles it into static HTML or into javascript template function.
pugjs/pug-loaderpugjs/pug-loader at webpack startingpugjs/pug-loader at webpack watching during compile changes in dependenciesresolve.alias, work fine with and without the prefixes ~ or @, e.g. this works:
extends UIComponents/layout.pugextends ~UIComponents/layout.pugextends @UIComponents/layout.puginclude UIComponents/mixins.puginclude ~UIComponents/mixins.puginclude @UIComponents/mixins.puginclude:markdown-it UIComponents/components.md- const colors = require('UIComponents/colors.json')img(src=require('UIComponents/image.jpeg'))const tmpl = require('UIComponents/index.pug');const tmpl = require('template.pug');
const html = tmpl({ var1: "value1" })
{method:'render'} or query parameter ?pug-render), e.g.:
const html = require('template.pug?pug-render&{var1:"value1"}');
Why use this particular pug loader instead of the original one?
pugjs/pug-loader is outdated and not maintained morepugjs/pug-loader has error by npm install see issue:
npm ERR! Found: pug@3.0.2 ... pug-loader@2.4.0" has incorrect peer dependency "pug@^2.0.0"resolve.alias also without the prefix ~pugjs/pug-loaderInstall
Webpack config
Options
Usage in Pug templates
Usage in JavaScript
Usage method compile in JavaScript
Usage method render in JavaScript
Usage method html in JavaScript
Usage with Angular Component
Passing data into template
Usage embedded resources
More examples of usages
npm install @webdiscus/pug-loader --save-dev
For usage pug templates only in javascript is enough add to a webpack config:
{
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
}
]
}
}
Or you can define the resolveLoader.alias to use the pug-loader as default pug loader name:
{
resolveLoader: {
alias: {
'pug-loader': '@webdiscus/pug-loader'
}
},
...
module: {
rules: [
{
test: /\.pug$/,
loader: 'pug-loader',
}
]
}
}
For rendering pug templates into static HTML is needed the HtmlWebpackPlugin.
The complete example of the webpack config file:
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
// The absolute path to the base directory of application.
const basePath = path.resolve(__dirname);
// The minimal required options for pug-loader.
const pugLoaderOptions = {};
module.exports = {
resolve: {
// aliases used in the code examples below
alias: {
UIComponents: path.join(basePath, 'src/lib/components/ui/'),
Images: path.join(basePath, 'src/images/'),
Templates: path.join(basePath, 'src/templates/'),
}
},
resolveLoader: {
// alias for pug-loader
alias: {
'pug-loader': '@webdiscus/pug-loader'
}
},
entry: {
// the script used a pug template
'script': './src/js/script.js',
},
output: {
path: path.join(basePath, 'public'),
filename: '[name].js',
assetModuleFilename: 'assets/images/[hash][ext][query]',
},
plugins: [
// this plugin extract the content of a pug template
// and save compiled via pug-loader content into html file
new HtmlWebpackPlugin({
template: path.join(basePath, '/src/templates/index.pug'),
filename: './public/index.html',
inject: false
}),
],
module: {
rules: [
{
test: /\.pug$/,
loader: 'pug-loader',
options: pugLoaderOptions
},
// it is need for usage embedded resources in pug, like img(src=require('./image.jpeg'))
{
test: /\.(png|jpg|jpeg)/,
type: 'asset/resource'
}
]
}
};
See original description of options
doctypeType: string
Default: html
Specifies the type of document. See available doctypes.
prettyType: boolean
Default: false
This option is deprecated by pugjs and always is false. Don't use it.
filtersType: object
Default: undefined
Hash table of custom filters.
Filters let to use other languages in Pug templates.
selfType: boolean
Default: false
Use the self as namespace for the local variables in template. It will speed up the compilation, but for access to variable, e.g. myVariable, you must write self.myVariable.
compileDebugType: boolean
Default: false
Includes the function source in the compiled template to improve error reporting.
globalsType: Array<string>
Default: []
Add a list of global names to make accessible in templates.
pluginsType: Array<Object>
Default: []
Plugins allow to manipulate pug tags, template content in compile process.
How it works see in source of pug.
methodType: string
Default: compile
Values:
compile the pug template compiles into a template function and in JavaScript can be called to render with variables into HTML at runtime, see usage >> \render the pug template compiles into a template function and by require() in JavaScript will automatically render to HTML at runtime, see usage >>html the template renders directly into a pure HTML string at compile time, see usage >>With methods
compileandrenderan embedded resource such asimg(src=require('./image.jpeg'))handles at compile time by the webpack usingasset/resource.
The method
htmlneed an additional loader, e.g.html-loader, to handle the HTML string and an embedded resource.
⚠ Limitation: an embedded resource such asimg(src='./image.jpeg')must be assigned in pug withoutrequire()function, otherwise appear error:require() not found.
dataType: Object
Default: {}
The custom data will be passed in all pug templates, it can be useful by pass global data.
The example of simple file structure of an application under the path /srv/vhost/sample.com/:
.
├--public/
├--lib/
| └--components/
| ├--ui/
| | ├--layout.pug
| | ├--mixins.pug
| | └--colors.json
| ...
├--src/
| ├--images/
| | ├--image.jpeg
| | ├--image1.jpeg
| | ├--image2.jpeg
| | └--image3.jpeg
| ├--js/
| | ├--script.js
| | └--data.json
| └--templates/
| ├--index.pug
| └--mixins.pug
| ├--widget.pug
└--webpack.config.js
The source Pug templates from src/templates/ after compilation are saved as HTML files in public/.
File ./src/templates/index.pug
extends UIComponents/layout.pug
include UIComponents/mixins.pug
block content
- const colors = require('UIComponents/colors.json')`
.color-container
+show-colors(colors)
File ./lib/components/ui/layout.pug
html
head
block head
body
block content
File ./lib/components/ui/mixins.pug
mixin show-colors(colors)
each color in colors
div(style=`background-color:${color.hex};`)= color.name
File ./lib/components/ui/colors.json
[
{
"name": "red",
"hex": "#f00"
},
{
"name": "green",
"hex": "#0f0"
},
{
"name": "blue",
"hex": "#00f"
}
]
In the sample above uses Webpack alias UIComponents instand of relative path ../../lib/components/ui/.
This pug loader resolve all paths and aliases in Pug templates required from JavaScript.
For example, see the file structure of the application above, the pug template can be loaded in JavaScript via require().
The result of require() is a template function, where the argument is an object of variableName:value, which are available in the pug template.
File ./src/js/script.js:
// 'Templates' is webpack alias
// 'widgetTemplate' is template function
const widgetTemplate = require('Templates/widget.pug');
// variables passed to the pug template
const locals = {
text: 'Hello World!',
colors: [
{
"name": "red",
"hex": "#f00"
},
{
"name": "green",
"hex": "#0f0"
},
{
"name": "blue",
"hex": "#00f"
}
]
}
// render template function with variables to HTML
const html = widgetTemplate(locals);
console.log(html);
File ./src/templates/widget.pug:
//- 'Templates' is webpack alias
include ~Templates/mixins
h2 Pug demo widget
//- the variables 'text' and `colors` are passed from 'script.js'
+widget(text, colors)
File ./src/templates/mixins.pug:
mixin widget(text, colors)
.widget
p= text
each color in colors
div(style=`color:${color.hex};`)= color.name
The result of console.log(html):
<h2>Pug demo widget</h2>
<div class='widget'>
<p>Hello World!</p>
<div style="color:#f00">red</div>
<div style="color:#0f0">green</div>
<div style="color:#00f">blue</div>
</div>
See the simple web app example >>
compile, render or html in JavaScriptcompile (default)In JavaScript the required template will be compiled into template function.
In webpack config add to module.rules:
{
test: /\.pug$/,
loader: 'pug-loader',
options: {
method: 'compile' // default method `compile` can be omitted
}
}
In JavaScript the result of require() must be called with some variables to render the template into HTML:
const tmpl = require('template.pug');
const html = tmpl({ key: 'value' });
Or add the query parameter ?pug-render to render into HTML:
const html = require('template.pug?pug-render');
Note: if the query parameter pug-render is set, then will be used rendering, independent of the loader option method.
renderRendering into HTML. This method compile the pug into template function, but by require() it will be transformed into HTML.
In webpack config add to module.rules:
{
test: /\.pug$/,
loader: 'pug-loader',
options: {
method: 'render'
}
}
In JavaScript can be used the result of require() as HTML string, automatically rendered at runtime:
const html = require('template.pug');
htmlRendering directly into pure HTML.
Note: additional loader html-loader is required.
In webpack config add to module.rules:
{
test: /\.pug$/,
use: [
{
loader: 'html-loader',
options: {
esModule: false,
},
},
{
loader: 'pug-loader',
options: {
method: 'html',
},
},
],
},
// Process image resources with webpack
{
test: /\.(png|jpg|jpeg)/,
type: 'asset/resource',
},
In JavaScript the template will be directly rendered into HTML:
const html = require('template.pug');
⚠ Limitation: an embedded resource must be assigned in pug without
require()function:img(src='./assets/image.jpeg')
Webpack config:
{
test: /\.pug$/,
loader: 'pug-loader'
}
JavaScript:
// compile into template function, because loader option 'method' defaults is 'compile'
const tmpl = require('template.pug');
const html = tmpl({...});
// render the pug file into HTML, using the parameter 'pug-render'
const html2 = require('template2.pug?pug-render');
Webpack config:
{
test: /\.pug$/,
loader: 'pug-loader',
options: {
method: 'render'
}
}
JavaScript:
// render directly into HTML, because loader option 'method' is 'render'
const html = require('template.pug');
// compile into template function, using the parameter 'pug-compile'
const tmpl2 = require('template2.pug?pug-compile');
const html2 = tmpl2({...});
For usage pug-loader with Angular is needed to customize the webpack config.
Install packages:
npm i --saveDev @webdiscus/pug-loader pug-plugin-ng
in pug-loader can be used optional a plugin, e.g. pug-plugin-ng, to allow unquoted syntax of Angular: [(bananabox)]="val"
Create the file webpack.config.js in root directory of angular project:
module.exports = {
resolveLoader: {
alias: {
'pug-loader': '@webdiscus/pug-loader',
},
},
module: {
rules: [
{
test: /\.pug$/,
loader: 'pug-loader',
options: {
method: 'render',
doctype: 'html',
plugins: [require('pug-plugin-ng')],
},
},
// Process image resources in pug templates with webpack
{
test: /\.(png|jpg|jpeg)/,
type: 'asset/resource',
},
],
},
};
Bind the file webpack.config.js in the Angular config file angular.json:
{
...
"projects": {
...
"architect": {
"build": {
// replace architect.build.builder with this value:
"builder": "@angular-builders/custom-webpack:browser",
// add the options:
"options": {
"aot": true,
"customWebpackConfig": {
"path": "./webpack.config.js" // the path to webpack.config.js
},
...
},
...
},
"serve": {
// replace architect.serve.builder with this value:
"builder": "@angular-builders/custom-webpack:dev-server",
"options": {
"browserTarget": "<app-name>:build"
},
...
},
...
}
}
},
}
In a component file, e.g. ./src/app/app.component.ts set the templateUrl with pug file:
import { Component } from '@angular/core';
// the variable `description` will be passed into pug template via resource query
const templateVars = '{"description": "Use pug template with Angular."}';
@Component({
selector: 'app-root',
styleUrls: ['./app.component.css'],
templateUrl: './app.component.pug?' + templateVars,
})
export class AppComponent {
title = 'ng-app';
}
Create a pug template, e.g. ./src/app/app.component.pug:
h1 Hello Pug!
p Description: #{description}
See the source files of this example >>
html-loaderInstall the html-loader:
npm i --saveDev html-loader
If your templates use the html-loader, then modify the webpack.config.js file:
module.exports = {
resolveLoader: {
alias: {
'pug-loader': '@webdiscus/pug-loader',
},
},
module: {
rules: [
{
test: /\.pug$/,
use: [
{
loader: 'html-loader',
options: {
esModule: false,
},
},
{
loader: 'pug-loader',
options: {
method: 'html', // the method render into HTML string and require additional loader `html-loader`
doctype: 'html',
plugins: [require('pug-plugin-ng')], // optional plugin
},
},
],
},
// Process image resources in pug templates with webpack
{
test: /\.(png|jpg|jpeg)/,
type: 'asset/resource',
},
],
},
};
See the source files of this example >>
By default, the pug file is compiled as template function, into which can be passed an object with template variables.
const tmpl = require('template.pug');
const html = tmpl2({
key: 'value',
foo: 'bar',
});
But how pass variables in template which is directly rendered into HTML?
const html = require('template.pug');
Variables can be passed with query parameters, e.g.:
const html = require('template.pug?key=value&foo=bar');
or as a JSON object, e.g.:
const html = require('template.pug?{"key":"value","foo":"bar"}');
Using the method render and JSON object:
const html = require('template.pug?pug-render&{"key":"value","foo":"bar"}');
Usage of query parameters is legal and official documented feature of webpack loader.
To pass variables global, in all templates at compile time use loader option data:
{
test: /\.pug$/,
loader: 'pug-loader',
options: {
data: {
key: 'value',
foo: 'bar'
}
}
}
The variables will be passed in all templates independent of the method.
For processing image resources in templates with webpack use the require() function:
img(src=require('./path/to/image.jpeg'))
For usage embedded resources is need add an asset-module to module.rules in webpack config:
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|jpeg)/,
type: 'asset/resource'
}
]
},
};
More information about asset-modules see here.
Due to the peculiarities of the pug compiler,
the interpolation of the argument to the require() function depends on its string and variable parts.
Use a relative path only in the string before the variable.
The variable must contain only the filename without specifying a path.
Examples of incorrect usage:
- filename = './image.jpeg'
img(src=require(filename))
- filename = '../relative/path/to/resource/image.jpeg'
img(src=require(filename))
Examples of correct usage:
- filename = 'image.jpeg'
img(src=require(filename))
- filename = 'image.jpeg'
img(src=require('../relative/path/to/resource/' + filename))
The example of dynamically generating embedded resources in template:
- files = ['image1.jpeg', 'image2.jpeg', 'image3.jpeg']
each file in files
img(src=require('../images/' + file))
The example of webpack alias used in the table below:
resolve: {
alias: {
SourceImages: path.join(__dirname, 'src/images/'),
},
}
Examples for using embedded resources:
| Code | @webdiscus/pug-loader | pugjs/pug-loader | Note |
|---|---|---|---|
img(src=require('image.jpeg')) | OK | fail | |
img(src=require('./image.jpeg')) | OK | OK | |
img(src=require('./images/image.jpeg')) | OK | OK | |
img(src=require('../images/image.jpeg')) | OK | OK | |
img(src=require('SourceImages/image.jpeg')) | OK | OK | Usage of the webpack alias to images directory. |
- file = 'image.jpeg'img(src=require('SourceImages/' + file)) | OK | OK | |
- file = 'image.jpeg'img(src=require(`SourceImages/${file}`)) | OK | OK | |
- file = 'image.jpeg'img(src=require(file)) | OK | fail | |
- file = 'image.jpeg'img(src=require(`${file}`)) | OK | fail | |
- file = 'image.jpeg'img(src=require('./' + file)) | OK | OK | |
- file = './image.jpeg'img(src=require(file)) | fail | fail | Don't use ./ in variable of filename. |
- file = './image.jpeg'img(src=require('' + file)) | fail | OK | Don't use ./ in variable of filename. |
- file = 'images/image.jpeg'img(src=require(file)) | OK | fail | |
- file = 'image.jpeg'img(src=require('./images/' + file)) | OK | OK | |
- file = 'image.jpeg'img(src=require(`./images/${file}`)) | OK | OK | |
- file = '../images/image.jpeg'img(src=require(file)) | fail | fail | Don't use a path in a variable. |
- file = 'image.jpeg'img(src=require('../images/' + file)) | OK | OK | Define a path separately as string and add to she the variable contained only a filename. |
- file = 'image.jpeg'img(src=require(`../images/${file}`)) | OK | OK | |
Include the template from sub directory: include mixinsimg(src=require('./image.jpeg')) | OK | fail | when use a mixin and require on same file, then pugjs/pug-loader can't resolve the file in require(). |
More examples of usages see in test cases.
Important: in examples used name of loader as
pug-loader, because it is defined as alias at resolveLoader:{ resolveLoader: { alias: { 'pug-loader': '@webdiscus/pug-loader' } }, }
1.2.0 (2021-11-12)
html to render the template function into pure HTML string,html-loaderFAQs
Pug loader renders Pug files into HTML or compiles them into a template function.
The npm package @webdiscus/pug-loader receives a total of 2,378 weekly downloads. As such, @webdiscus/pug-loader popularity was classified as popular.
We found that @webdiscus/pug-loader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.