@webdiscus/pug-loader
Advanced tools
Pug loader renders Pug files into HTML or compiles them into a template function.
Pug loader renders Pug files into HTML or compiles them into a template function.
This Pug loader resolves paths and aliases for extends include require().
π‘New: now is supported an indent in Vue template.
MyComponent.vue
<template lang='pug'> h1 Hello Pug! p Use the '@webdiscus/pug-loader' </template>Why is this Pug loader best for Vue?
Features @webdiscus/pug-loaderpug-plain-loaderindent in <templatΠ΅ lang='pug'>β β render into HTML β β render into template function β β pass custom data to template β β embedded filter :highlightβ β embedded filter :markdownβ β test coverage > 98% 0% last update right now 4 years ago See setup and usage example.
π‘ 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 required 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.
HTML stringtemplate function for usage in JavaScriptCommonJS and ESM syntaxresolve.aliastsconfig.json compilerOptions.paths,
requires tsconfig-paths-webpack-pluginsrcset of img tag:escape :code :highlight :markdown with highlighting of code blocksChoose your way:
pug-plugin.
It is a very easy intuitive way.pug-pluginFor details and examples please see the pug-plugin site.
Install the pug-plugin:
npm install pug-plugin --save-dev
Note: the pug-plugin already contains the pug-loader, not need to install an additional Pug loader.
β οΈ ATTENTION
The pug-plugin enable to use script and style source files directly in Pug, so easy:
link(href=require('./styles.scss') rel='stylesheet') script(src=require('./main.js'))Generated HTML contains hashed CSS and JS output filenames:
<link href="/assets/css/styles.05e4dd86.css" rel="stylesheet"> <script src="/assets/js/main.f4b855d8.js"></script>
- Don't define styles and JS files in entry. You can use
require()for source files of JS and SCSS in Pug.- Don't import styles in JS. Use
require()for style files in Pug.- Don't use
html-webpack-pluginto render Pug files in HTML. The Pug plugin processes files from webpack entry.- Don't use
mini-css-extract-pluginto extract CSS from styles. The Pug plugin extract CSS from styles required in Pug.
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, 'dist/'),
publicPath: '/', // must be defined any path, `auto` is not supported
// output filename of JS files
filename: 'assets/js/[name].[contenthash:8].js'
},
entry: {
// all scripts and styles can be used in Pug,
// do not need to define JS and SCSS in the webpack entry
// define Pug files in entry:
index: './src/views/index.pug', // output index.html
about: './src/views/about/index.pug' // output about.html
// ...
},
plugins: [
// enable processing of Pug files from entry
new PugPlugin({
modules: [
// module extracts CSS from style source files required in Pug
PugPlugin.extractCss({
// output filename of CSS files
filename: 'assets/css/[name].[contenthash:8].css'
})
]
})
],
module: {
rules: [
{
test: /\.pug$/,
loader: PugPlugin.loader, // PugPlugin already contain the pug-loader
options: {
method: 'render', // fastest method to generate static HTML files
}
},
{
test: /\.(css|sass|scss)$/,
use: ['css-loader', 'sass-loader']
},
],
},
};
Install 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 teplate 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 the following to the pug-loader options:
{
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.
See the complete information on the pug filter site and in the sources.
compile methodThis method is used by 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.
render methodThis 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({ ... });
html methodThis 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
The goal of embedded filters is to use most useful lightweight filters without installation.
The embedded filters are custom filters that are collected in one place.
These filters can be simply enabled via an option.
See the complete information on the pug filter site and in the sources.
Defaults all embedded filters are disabled. Enable only filters used in your Pug templates.
:escapeThe filter replaces reserved HTML characters with their corresponding HTML entities to display these characters as text.
Filter options: none.
Enable the filter:
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
// enable embedded filters
embedFilters: {
escape: true, // enable the :escape filter
},
},
},
Using the :escape filter in pug:
pre: code.language-html
:escape
<h1>Header</h1>
Generated HTML:
<pre>
<code class="language-html">
<h1>Header</h1>
</code>
</pre>
Inline syntax:
p.
The #[:escape <html>] element is the root element.<br>
Inside the #[:escape <html>] element there is a #[:escape <body>] element.
Generated HTML:
<p>The <html> element is the root element.<br>
Inside the <html> element there is a <body> element.</p>
For more information and examples, see the :escape site.
:codeThe filter wraps a content with the <code> tag.
Filter options:
className {string} The class name of the code tag. For example, the prismjs use the language-* as class name in <code> for styling this tag.Enable the filter:
{
test: /\.pug$/,
loader: '@webdiscus/pug-loader',
options: {
// enable embedded filters
embedFilters: {
// enable the :code filter
code: {
className: 'language-', // class name of `<code>` tag, needed for `prismjs` theme
},
},
},
},
Usage examples:
Pug: #[:code function() { return true }]
Display: function() { return true }
Pug: #[:code:escape <div>]
Display: <div>
Pug: #[:code:highlight(html) <div class="container">content</div>]
Display highlighted code: <div class="container">content</div>
For more information and examples, see the :code site.
:highlightThe filter highlights code syntax.
Filter options:
verbose {boolean} Enable output process info in console.use {string} The name of a highlighting npm module. The module must be installed. Currently, is supported the prismjs only.Enable the filter:
{
embedFilters: {
highlight: {
verbose: true,
use: 'prismjs',
},
},
}
Usage example:
pre.language-: code
:highlight(html)
<!-- Comment -->
<h1>Header</h1>
<p>Text</p>
For more information and examples, see the :highlight site.
:markdownThe filter transform markdown to HTML and highlights code syntax.
The :markdown filter require the markdown-it and prismjs modules:
npm install -D markdown-it prismjs
Enable the filter:
{
test: /.pug$/,
loader: '@webdiscus/pug-loader',
options: {
// enable embedded filters
embedFilters: {
// enable :markdown filter
markdown: {
// enable highlighting in markdown
highlight: {
verbose: true,
use: 'prismjs',
},
},
},
},
},
The highlight options:
verbose {boolean} Enable output process info in console. Use it in development mode only. Defaults is false.use {string} The name of a highlighting npm module. The module must be installed. Currently, is supported the prismjs only.Usage example:
:markdown
_HTML_
```html
<!-- Comment -->
<div class="container">
<p>Paragraph</p>
</div>
```
_JavaScript_
```js
const arr = [1, 2, 'banana'];
```
Display highlighted code blocks:
HTML
<!-- Comment --> <div class="container"> <p>Paragraph</p> </div>JavaScript
const arr = [1, 2, 'banana'];
For more information and examples, see the :markdown site.
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'))
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')) | β 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 --save-dev @webdiscus/pug-loader pug-plugin-ng
In pug-loader can be used the optional 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.
Install:
npm i --save-dev @webdiscus/pug-loader
Change your vue.config.js according to the following minimal configuration:
const { defineConfig } = require('@vue/cli-service');
// additional pug-loader options,
// e.g. to enable pug filters such as `:highlight`, `:markdown`, etc.
// see https://github.com/webdiscus/pug-loader#options
const pugLoaderOptions = {
};
module.exports = defineConfig({
transpileDependencies: true,
chainWebpack: (config) => {
const pugRule = config.module.rule('pug');
// clear all existing pug loaders
pugRule.uses.clear();
pugRule.oneOfs.clear();
},
configureWebpack: {
module: {
rules: [
{
test: /\.pug$/,
oneOf: [
// allow import of Pug in JavaScript
{
exclude: /\.vue$/,
loader: '../../',
options: {
method: 'compile', // compile Pug into template function
...pugLoaderOptions,
},
},
// allow <template lang="pug"> in Vue components
{
loader: '../../',
options: {
method: 'html', // render Pug into pure HTML string
...pugLoaderOptions,
},
},
],
},
],
},
},
});
Usage Pug in Vue template
<templatΠ΅ lang='pug'>
h1 Hello Pug!
p Paragraph
</templatΠ΅>
Note: you can use an indent for Pug code in Vue template.
Usage Pug in JavaScript
App.vue
<template>
<div v-html='html'></div>
</template>
<script>
import tmpl from './views/demo.pug';
// define custom data used in Pug template
const locals = { colors: ['red', 'green', 'blue'] };
// pass custom data in Pug template
const rawHtml = tmpl(locals);
export default {
name: 'App',
data() {
return {
html: rawHtml
}
}
}
</script>
demo.pug
each color in colors
div(style=`color: ${color}`) #{color}
Note: the colors is external variable passed from App.vue.
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.
2.4.0 (2022-05-25)
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.