@webdiscus/pug-loader
Advanced tools
Pug loader resolves paths and webpack aliases in a pug template and compiles it to HTML or into a template function.
This pug-loader render pug templates into HTML to save it in a
file or compile pug to template function for usage the pug directly in JavaScript.
The pug loader can resolve paths and webpack aliases for extends include require().
ā ļø HIGHLY RECOMMENDED to use the pug-plugin.
Pug plugin makes your life a lot easier. Keep your webpack config clean and clear.This
pug-loaderis already included in the pug-plugin.
Thepug-pluginenable using Pug templates as webpack entry points.
Thepug-pluginresolve and compile source files of scripts and styles included directly in Pug, without to define them in the webpack entry. You don't need more additional plugins such ashtml-webpack-pluginandmini-css-extract-plugin. Pug plugin does everything by itself and much faster.Please see usage examples and the demo app Hello World.
compilerenderhtmlHTML string to save it in separate filetemplate function for usage in JavaScriptCommonJS and ESM syntaxresolve.aliascompilerOptions.paths defined in tsconfig.json
using tsconfig-paths-webpack-pluginsrcset of img tag:escape~ @ for webpack resolve.aliasAngular Componentpugjs/pug-loaderpugjs/pug-loaderTo extract HTML from a pug template and save it to a file, use the pug-plugin or html-webpack-plugin.
pug-pluginInstall the pug-plugin if you want extract HTML from pug defined in webpack entry.
npm install pug-plugin --save-dev
Note: the
pug-pluginalready contain thepug-loader, not need to install extra anypug-loader.
Change your webpack.config.js according to the following minimal configuration:
const path = require('path');
const PugPlugin = require('pug-plugin');
module.exports = {
output: {
path: path.join(__dirname, 'public/'),
publicPath: '/', // must be defined any path, `auto` is not supported yet
},
entry: {
index: './src/index.pug', // the `pug-plugin` extract HTML from entry file
},
plugins: [
new PugPlugin(), // add it to handle pug files in entry
],
module: {
rules: [
{
test: /\.pug$/,
loader: PugPlugin.loader, // the pug-plugin already contain this pug-loader
options: {
method: 'render', // the fastest method to generate HTML files
}
},
],
},
};
html-webpack-pluginInstall the pug-loader only if you use the html-webpack-plugin.
npm install @webdiscus/pug-loader --save-dev
Change your webpack.config.js according to the following minimal configuration:
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
output: {
path: path.join(__dirname, 'public/'),
publicPath: '/', // must be defined any path, `auto` is not supported yet
},
plugins: [
new HtmlWebpackPlugin({
template: path.join(__dirname, 'src/index.pug'),
filename: 'index.html',
}),
],
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
},
],
},
};
Install the pug-loader.
npm install @webdiscus/pug-loader --save-dev
Change your webpack.config.js according to the following minimal configuration:
const path = require('path');
module.exports = {
output: {
path: path.join(__dirname, 'public/'),
publicPath: '/', // must be defined any path, `auto` is not supported yet
},
entry: {
index: './src/index.js', // load a pug file in JS
},
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
},
],
},
};
Load a pug template in JavaScript. Optional you can pass any data into generated template function.
./src/index.js
const tmpl = require('template.pug');
const html = tmpl({
myVar: 'value',
});
See original description of options
basedirType: string Default: /
The root directory of all absolute inclusion.
doctypeType: string Default: html
Specifies the type of document. See available doctypes.
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.
globalsType: Array<string> Default: []
Add a list of global names to make accessible in templates.
filtersType: object Default: undefined
Hash table of custom filters.
Filters let to use other languages in Pug templates.
pluginsType: Array<Object> Default: []
Plugins allow to manipulate pug tags, template content in compile process.
How it works see in source of pug.
compileDebugType: boolean Default: false
Includes the function source in the compiled template to improve error reporting.
prettyType: boolean Default: false
This option is deprecated by pugjs and always is false. Don't use it.
methodType: string Default: compile
Values:
compile the pug template compiles into a template function and in JavaScript can be called with variables to render into HTML at runtime. ?pug-compile. Can be used if the method is render. render the pug template renders into HTML at compile time and exported as a string.
All required resource will be processed by the webpack and separately included as added strings wrapped to a function. ?pug-render. Can be used if the method is compile or is not defined in options. html the template renders into a pure HTML string at compile time. The method need an addition loader to handles the HTML. html-loader see usageEmbedded resources such as
img(src=require('./image.jpeg'))handles at compile time by the webpack using asset/resource.
esModuleType: Boolean Default: false
Enable / disable ESM syntax in generated JS modules.
Values:
true The pug-loader generates JS modules with the ESM syntax. import html from 'template.pug';. false defaults. The pug-loader generates JS modules with the CommonJS modules syntax. const html = require('template.pug'). false for compatibility with the JS modules that is generated by the original pug-loader.Note: The option
esModuleis irrelevant for thehtmlmethod, because it returns a pure HTML string.
š” For generates smaller and faster template function, it is recommended to use following options:
{
method: 'render',
esModule: true,
}
dataType: Object Default: {}
The custom data will be passed in all pug templates, it can be useful by pass global data.
ā ļø Limitation by the
compilemethod.
A string representing the source code of the function is limited by thefunction.toString(), see examples.
For native work of the function passed via thedataloader option, use therendermethod.
embedFiltersType: Object Default: undefined
Enable embedded pug filters.
To enable a filter add to pug-loader options following:
{
embedFilters: {
<FILTER_NAME> : <FILTER_OPTIONS> | <TRUE>,
}
}
Where <FILTER_NAME> is the name of a embedded filter, the available filters see below.
The filter can have options <FILTER_OPTIONS> as an object.
If the filter has no options, use true as an option to enable the filter.
ā ļø Defaults all embedded filters are disabled!
Enable only filters used in your pug templates.
š” We have currently only one embedded filter, but other useful filters will occasionally be added.
The goal of the embedded filters is use fast and lightweight filters without additional dependencies in package.json. Here we want collect most useful small filters. It is like custom filters, but already exists in the filter collection, that can be simply via an option enabled.
In issues, you can suggest your own filter, and we can add it.
escapePug filter: :escape Filter options: none
The filter escapes HTML tags to display HTML code in the browser as plain text.
This is useful when using syntax highlighting for code containing HTML tags.
Enable the filter:
{
embedFilters: {
escape: true,
},
}
Using the :escape filter in pug:
pre: code.language-html
:escape
<!-- HTML -->
<div>
<p>Text</p>
</div>
Generates plain text:
<pre>
<code class="language-html">
<!-- HTML -->
<div>
<p>Text</p>
</div>
</code>
</pre>
Display in browser:
<!-- HTML -->
<div>
<p>Text</p>
</div>
Inline syntax:
p
:escape The <strong> element has the closing </strong> tag.
p.
The #[:escape <html>] element is the root element.<br>
Inside the #[:escape <html>] element there is a #[:escape <body>] element.
Generates plain text:
<p>
The <strong> element has the closing </strong> tag.
</p>
<p>
The <html> element is the root element.
<br>
Inside the <html> element there is a <body> element.
</p>
compile (default)In JavaScript the required template will be compiled into template function.
In webpack config add to module.rules:
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
method: 'compile' // default method `compile` can be omitted
}
}
In JavaScript, the result of require() is a template function. Call the template function with some variables to render it to HTML.
const tmpl = require('template.pug');
const html = tmpl({ key: 'value' }); // the HTML string
To render the pug direct into HTML, use the query parameter ?pug-render.
// compile into template function, because loader option 'method' defaults is 'compile'
const tmpl = require('template.pug');
const html = tmpl({ key: 'value' });
// render the pug file into HTML, using the parameter 'pug-render'
const html2 = require('template2.pug?pug-render');
Note: if the query parameter
pug-renderis set, then will be used rendering for this template, independent of the loader optionmethod. Variables passed in template with methodrenderwill be used at compile time.
renderThis method will render the pug into HTML at compile time.
In webpack config add to module.rules:
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
method: 'render'
}
}
In JavaScript the result of require() is an HTML string.
const html = require('template.pug'); // the HTML string
To generate a template function for passing the data in pug at realtime, use the query parameter ?pug-compile.
// render 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({ ... });
htmlThis method will render the pug to pure HTML and should be used with an additional loader to handle HTML.
In webpack config add to module.rules:
{
test: /\.pug$/,
use: [
{
loader: 'html-loader',
options: {
esModule: false, // allow to use the require() for load a template in JavaScript
},
},
{
loader: '@webdiscus/pug-loader',
options: {
method: 'html',
},
},
],
}
In JavaScript the result of require() is an HTML string:
const html = require('template.pug'); // the HTML string
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 = tmpl({
myVar: 'value',
foo: 'bar'
});
But how pass variables in template which is rendered into HTML?
Variables can be passed with query parameters.
const html = require('template.pug?myVar=value&foo=bar');
or as a JSON object:
const html = require('template.pug?' + JSON.stringify({ myVar: 'value', foo: 'bar' }));
Use variables myVar and foo in pug template.
div The value of "myVar": #{myVar}
div The value of "foo": #{foo}
Usage of query parameters is legal and official documented feature of webpack loader.
Pass myData object via query.
entry: {
about: './src/pages/about.pug?myData=' + JSON.stringify({ title: 'About', options: { uuid: 'abc123' } })
}
Use the object myData in pug template.
html
head
title= myData.title
body
div UUID: #{myData.options.uuid}
To pass global data to all pug templates, add the loader options data as any object.
module.exports = {
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
data: {
htmlLang: 'en-EN',
getKeywords: () => {
const keywords = ['webpack', 'pug', 'loader'];
return keywords.join(',');
}
}
}
},
],
},
};
Use the custom data and function in pug.
html(lang=htmlLang)
head
meta(name="keywords" content=getKeywords())
body
The user data can be passed into pug template with two ways:
module.exports = {
plugins: [
new HtmlWebpackPlugin({
title: 'The some page', // avaliable in pug as `htmlWebpackPlugin.options.title`
template: path.join(__dirname, 'src/index.pug?' + JSON.stringify({ myVar: 'value' })), // avaliable as `myVar`
filename: 'index.html',
}),
],
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
},
],
},
};
Use the passed variables htmlWebpackPlugin.options and myVar in pug template:
html
head
title= htmlWebpackPlugin.options.title
body
div= myVar
You can load data directly in pug.
data.json
[
{ "id": 1, "name": "abc" },
{ "id": 2, "name": "xyz" }
]
Require the JSON file in pug.
- var myData = require('./data.json')
each item in myData
div #{item.id} #{item.name}
To handle resources in pug with webpack use the require() function:
img(src=require('./path/to/image.jpeg'))
For images, add the following rule to the webpack module:
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|jpeg|svg|ico)/,
type: 'asset/resource',
generator: {
filename: 'assets/images/[name].[hash:8][ext]',
},
},
]
},
};
For fonts, add the following rule to the webpack module:
module.exports = {
module: {
rules: [
{
test: /\.(woff2|woff|ttf|svg|eot)/,
type: 'asset/resource',
generator: {
filename: 'assets/fonts/[name][ext]',
},
},
]
},
};
More information about asset-modules see here.
Example of dynamic interpolation of image src in pug:
- files = ['image1.jpeg', 'image2.jpeg', 'image3.jpeg']
each file in files
img(src=require(`./path/to/${file})`)
The file in the current directory MUST start with ./:
img(src=require('./image.jpeg'))
img(src=require('./sub/path/to/image.jpeg'))
The file in the parent directory MUST start with ../:
img(src=require('../images/image.jpeg'))
The relative path from loader option basedir MUST start with /:
loader: '@webdiscus/pug-loader',
options: {
basedir: path.resolve(__dirname, './src')
}
img(src=require('/assets/images/image.jpeg')) <-- relative path from the basedir
The file in the directory defined by webpack aliase MAY start with ~ or @, e.g. with the alias Images: path.join(__dirname, 'src/assets/images/'):
img(src=require('Images/image.jpeg'))
img(src=require('~Images/image.jpeg'))
img(src=require('@Images/image.jpeg'))
ā ļø Using a variable with the compile method has the limitation - the variable MUST NOT contain a path, only a filename, because is interpolated at compile time:
- const file = 'image.jpeg'
img(src=require('./path/to/' + file)) // sub directory
img(src=require('../path/to/' + file)) // parent directory
img(src=require('/path/to/' + file)) // option.base directory
img(src=require('~Images/' + file)) // webpack alias
but in current directory, the filename MUST start with ./:
- const file = './image.jpeg'
img(src=require(file))
ā ļø Using an alias from the paths defined in tsconfig.json with the compile method has the limitation - the required argument MUST be a string only, the webpack not supports an expression with alias:
tsconfig.json
{
"compilerOptions": {
"paths": {
"@Images/*": ["assets/images/*"]
}
}
}
- const file = './image.jpeg'
img(src=require('@Images/image.jpeg')) // webpack alias resolved via `resolve.plugiins` from `tsconfig.json`
img(src=require('@Images/' + file)) // ERROR: Can't resolve '@Images' in require expression.
Using a variable with render and html methods has no limitation - the variable MAY contain a path, because is resolved at runtime:
- const file = '../parent/path/to/image.jpeg'
img(src=require(file))
img(src=require('~Images/' + file))
img(src=require('@Images/' + file))
The example of webpack alias used in the table below:
resolve: {
alias: {
Images: path.join(__dirname, 'src/assets/images/'),
},
}
| Example in pug template | @webdiscus/ pug-loader render / html methods | @webdiscus/ pug-loader compile method | pugjs/ pug-loader |
|---|---|---|---|
img(src=require('logo.png')) | ā but not recomended | ā | ā |
img(src=require('./logo.png')) | ā | ā | ā |
img(src=require('../images/logo.png')) | ā | ā | ā |
img(src=require('~Images/logo.png')) | ā | ā | ā |
- var file = 'logo.png'img(src=require(`~Images/${file}`)) | ā | ā | ā |
- var file = './logo.png'img(src=require(file)) | ā | ā | ā |
- var file = './images/logo.png'img(src=require(file)) | ā | ā | ā |
- var file = '../images/logo.png'img(src=require(file)) | ā | ā | ā |
- var file = 'logo.png'img(src=require(`./images/${file}`)) | ā | ā | ā |
- var file = 'logo.png'img(src=require('../images/' + file)) | ā | ā | ā |
pugjs/pug-loader can't resolve a resourcewhen used a mixin and require in same file: include mixinsimg(src=require('./logo.png')) | ā | ā | ā |
Install
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 = {
module: {
rules: [
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
method: 'render',
doctype: 'html',
plugins: [require('pug-plugin-ng')],
},
},
],
},
};
Bind the file webpack.config.js in the Angular config 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 complete source of the example.
srcset in img tagimg(srcset=`${require('./image1.jpeg')} 320w, ${require('./image2.jpeg')} 640w` src=require('./image.jpeg'))
output
<img srcset="/assets/image1.f78b30f4.jpeg 320w, /assets/image2.f78b30f4.jpeg 640w" src="/assets/image.f78b30f4.jpeg">
Use the require() for CommonJS files in pug templates.
The JS module say-hello.js
module.exports = function(name) {
return `Hello ${name}!`;
}
Use the module sayHello in pug template.
- var sayHello = require('./say-hello')
h1 #{sayHello('pug')}
npm run test will run the unit and integration tests.
npm run test:coverage will run the tests with coverage.
ansis - ANSI color styling of text in terminalpug GitHubpug API Referencepug-plugin2.1.1 (2022-05-11)
FAQs
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.