The Pug Plugin generates static HTML or template function from Pug template containing source files of scripts, styles, images, fonts and other resources, similar to how it works in Vite. This plugin allows using a template file as an entry point.
The plugin resolves source files of assets in templates and replaces them with correct output URLs in the generated HTML. The resolved assets will be processed via Webpack plugins/loaders and placed into the output directory. You can use a relative path or Webpack alias to a source file.
A template imported in JS will be compiled into template function. You can use the template function in JS to render the template with variables in runtime on the client-side in the browser.
- An entry point is the Pug template.
- Auto processing multiple templates in the entry path.
- Allows to specify
script
andstyle
source files directly in Pug:link(href="./style.scss" rel="stylesheet")
script(src="./app.tsx" defer="defer")
- Resolves source files in default attributes
href
src
srcset
etc. using relative path or alias:link(href="../images/favicon.svg" type="image/svg" rel=icon)
img(src="@images/pic.png" srcset="@images/pic400.png 1x, @images/pic800.png 2x")
- Inlines JS and CSS into HTML.
- Inlines images into HTML and CSS.
- Compile the Pug template into template function for usage in JS on the client-side.
- Generates the preload tags for fonts, images, video, scripts, styles, etc.
- Generates the integrity attribute in the
link
andscript
tags. - Generates the favicons of different sizes for various platforms.
- Built-in filters:
:escape
:code
:highlight
:markdown
. - You can create own plugin using the Plugin Hooks.
See the full list of features.
Note
โผ๏ธ All features and options of the html-bundler-webpack-plugin available now in thepug-plugin
too.
Warning
Since the version
5.0.0
, the Pug plugin is essentially the html-bundler-webpack-plugin preconfigured for using Pug templates.
Warning
Compared to the version
4.x
, in the new version5.x
the source asset file can be specified in a template without therequire()
function. For compatibility, therequire()
function is still supported.//- OLD syntax: the path is relative to the partial file or can be as the webpack alias link(href=require("./style.scss") rel="stylesheet") //- NEW syntax: the path is relative to the entry file or can be as the webpack alias link(href="./style.scss" rel="stylesheet")See the full list of the BREAKING CHANGES in v5.
๐ Table of Contents
โ๏ธ Pug Plugin options
Install the pug-plugin
:
npm install pug-plugin --save-dev
Install additional packages for styles:
npm install css-loader sass sass-loader --save-dev
For example, there is the Pug template with source asset files ./src/views/index.pug:
html
head
//- relative path to SCSS source file
link(href="../scss/style.scss" rel="stylesheet")
//- relative path to TypeScript source file
script(src="../app/main.js" defer="defer")
body
h1 Hello World!
//- relative path to image source file
img(src="../assets/images/picture1.png")
//- Webpack alias as path (src/assets/images/) to image source file
img(src="@images/picture2.png")
The minimal webpack config:
const PugPlugin = require('PugPlugin');
module.exports = {
plugins: [
new PugPlugin({
entry: {
// define many page templates here
index: 'src/views/index.pug', // => dist/index.html
},
js: {
// JS output filename
filename: 'js/[name].[contenthash:8].js',
},
css: {
// CSS output filename
filename: 'css/[name].[contenthash:8].css',
},
}),
],
module: {
rules: [
{
test: /\.(s?css|sass)$/,
use: ['css-loader', 'sass-loader'],
},
{
test: /\.(ico|png|jp?g|webp|svg)$/,
type: 'asset/resource',
generator: {
filename: 'img/[name].[hash:8][ext][query]',
},
},
],
},
};
Warning
No additional pug or html loaders required.
The generated HTML contains URLs of the output filenames:
<html>
<head>
<link href="css/style.05e4dd86.css" rel="stylesheet" />
<script src="js/main.f4b855d8.js" defer="defer"></script>
</head>
<body>
<h1>Hello World!</h1>
<img src="img/picture1.58b43bd8.png" />
<img src="img/picture2.bd858b43.png" />
</body>
</html>
The Pug plugin has all the options of the HTML Bundler Plugin
, plus a few options specific to Pug plugin.
Type: 'auto'|boolean|Object
Default: false
The Pug compiler generate minimized HTML.
For formatting generated HTML is used the js-beautify with the following default options
:
{
html: {
indent_size: 2,
end_with_newline: true,
indent_inner_html: true,
preserve_newlines: true,
max_preserve_newlines: 0,
wrap_line_length: 120,
extra_liners: [],
space_before_conditional: true,
js: {
end_with_newline: false,
preserve_newlines: true,
max_preserve_newlines: 2,
space_after_anon_function: true,
},
css: {
end_with_newline: false,
preserve_newlines: false,
newline_between_rules: false,
},
},
}
Possible values:
false
- disable formattingtrue
- enable formatting with default options'auto'
- indevelopment
mode enable formatting with default options, inproduction
mode disable formatting, use prettyOptions to customize options{}
- enable formatting with custom options, this object are merged withdefault options
see options reference
Type: Object
Default: null
When the pretty option is set to auto
or true
, you can configure minification options using the prettyOptions
.
Why the Pug Plugin since v5.0
based on html-bundler-webpack-plugin?
2021
The history of the creation of the pug-plugin
began back in October 2021.
Then, at the end of 2021, I created the @webdiscus/pug-loader that had all the features of the original pug-loader.
2022
Using, then without an alternative, html-webpack-plugin
caused me pain and suffering to configure webpack for rendering Pug templates containing various assets.
At the beginning of 2022, I started creating the pug-plugin
as a complete replacement for the html-webpack-plugin
and many other "crutches".
During of the year, the pug-plugin
has gained a lot of useful features and was able to replace the html-webpack-plugin
, mini-css-extract-plugin
and many other plugins and loaders.
2023
Based on the pug-plugin
code, I decided to create a universal html-bundler-webpack-plugin that would support all the most popular template engines, such as Eta, EJS, Handlebars, Nunjucks, Pug, TwigJS, and would be extendable for other template engines, e.g., LiquidJS.
During 2023, this plugin has gained even more useful features and absorbed all the functionality of the pug-plugin
and the @webdiscus/pug-loader
.
2024
At the beginning of 2024, the pug-plugin
completely switched to the universal code html-bundler-webpack-plugin
.
Starting from version 5.0
, the pug-plugin
is the html-bundler-webpack-plugin
pre-configured for Pug templates with the pre-installed pug
package.
The config of pug-plugin >= v5.0
:
const PugPlugin = require('pug-plugin');
module.exports = {
plugins: [
new PugPlugin({
entry: {
index: 'src/views/home.pug',
},
}),
],
};
is the same as:
const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
module.exports = {
plugins: [
new HtmlBundlerPlugin({
entry: {
index: 'src/views/home.pug',
},
preprocessor: 'pug', // <= enable using Pug templating engine
}),
],
};
The
pug-plugin
's heart now lives in thehtml-bundler-webpack-plugin
.
@webdiscus/pug-loader
->pug-plugin
->html-bundler-webpack-plugin
->pug-plugin
- ansis - The Node.js library for ANSI color styling of text in terminal
- pug-loader - The Pug loader for webpack
- html-bundler-webpack-plugin - The plugin handles HTML template as entry point, extracts CSS, JS, images from their sources loaded directly in HTML