This is a Pug template for the webpack plugin html-webpack-plugin. Inspired by another template, html-webpack-template.
In addition to the options that should cover most needs of a single-page app, a custom Pug file can be used to extend the provided layout.pug or to completely rewrite the template while utilizing mixins from mixins.pug.
Loading the template requires that pug-loader and consequently pug be available in node_modules.
Install the template with npm:
npm install html-webpack-template-pug --save-devor together with peer dependencies:
npm install pug pug-loader html-webpack-plugin html-webpack-template-pug --save-devRequired parameters, to be passed to new HtmlWebpackPlugin(options) as properties on options:
inject: false-- Disables resource injection by html-webpack-plugintemplate: providedlayout.pugor a custom*.pugfile.
Pug-loader should either be set for all *.pug files:
module: {
loaders: [
//...
{
test: /\.pug$/,
loader: 'pug-loader'
}
]
}or explicitly together with the template:
template: '!!pug-loader!custom_template.pug'Optional parameters:
-
appMountId: String or [String,...]-- Id or an array of ids for the<div>elements to be included in the<body>, for mounting JavaScript app, etc. -
mobile: Boolean = false-- Adds a meta tag for viewport size and page scaling on mobile. -
inline: String or [String,...]-- A chunk name or an array of chunk names to be inlined. A chunk name corresponds to the name of the entry point and can include:cssor:jspostfix to limit resources to be inlined to CSS or JavaScript respectively. -
excludeJSWithCSS: Boolean = false-- Excludes JavaScript files from chunks that contain CSS files. Intended for use cases when a JavaScript file (e.gstyle.js) is created as a byproduct of a CSS-only entry chunk (entry: {style: 'main.css'}). -
excludeJSChunks: String or [String,...]-- A chunk name or an array of chunk names. Excludes JavaScript files from specific chunks. Intended for use cases when a JavaScript file (e.gstyle.js) is created as a byproduct of a CSS-only entry chunk (entry: {style: 'main.css'}). -
injectExtras.head: [tag,...]-- An array of Objects representing tags to be injected in<head>. A tag can be:-
A String ending with ".css". Then the injected tag becomes
<link rel="stylesheet" href=tag>. -
A String ending with ".js". Then the injected tag becomes
<script src=tag></script>. -
An object with one required property tag that will serve as the tag name. All other properties will be set on the injected tag as its attributes. innerHTML property, if set, will be passed as content to non-self-closing tags.
-
To give an example:
{ tag: "meta", name: "description", content: "A description of the page" }
becomes
<meta name="description" content="A description of the page">
-
-
injectExtras.body: [tag,...]-- Same asinjectExtras.headbut to be injected at the bottom of the<body>.
And other options from html-webpack-plugin#configuration.
An example of webpack configuration utilizing the options above:
{
// ...
plugins: [
new HtmlWebpackPlugin({
// Required
inject: false,
template: require('html-webpack-template-pug'),
// template: '!!pug-loader!node_modules/html-webpack-template-pug/layout.pug'
// Optional
appMountId: 'app',
// appMountId: ['app1', 'app2']
mobile: true,
injectExtras: {
head: [
"https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css",
{
tag: 'link',
rel: 'dns-prefetch',
href: '//example.com/'
},
{
tag: 'base',
href: '../assets/page.html'
},
{
tag: 'meta',
name: 'description',
content: 'A description of the page'
}
],
body: [
'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.0/jquery.min.js',
'https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js',
{
tag: 'noscript',
innerHTML: "JavaScript is disabled in your browser. <a href='http://www.enable-javascript.com/' target='_blank'>Here</a> is how to enable it."
}
]
},
title: 'My App'
// Other html-webpack-plugin options...
})
]
}An example of webpack configuration with extracting a CSS-only entry chunk:
{
entry: {
app: './app',
style: './app/main.css'
},
output: {
path: './build',
filename: '[name].js'
},
module: {
loaders: [
// ...
{
test: /\.css$/,
loader: ExtractTextPlugin.extract('style', 'css')
}
]
},
// ...
plugins: [
new HtmlWebpackPlugin({
// Required
inject: false,
template: require('html-webpack-template-pug'),
// template: '!!pug-loader!node_modules/html-webpack-template-pug/layout.pug'
// Optional
excludeJSChunks: 'style', // don't include specific chunks in scripts (when .js is a byproduct of an already extracted .css)
// excludeJSChunks: ['style1', 'style2']
appMountId: 'app',
mobile: true,
title: 'My App'
// Other html-webpack-plugin options...
}),
new ExtractTextPlugin('[name].css')
]
}The layout.pug that is used by default with require('html-webpack-template-pug') amounts to the following:
include ./mixins.pug
doctype html
html(lang='en', manifest=htmlWebpackPlugin.files.manifest)
head
meta(charset='utf-8')
meta(http-equiv='X-UA-Compatible', content='IE=edge')
block defaultHead
+mobile
+title
+favicon
+injectExtrasHead
+CSS
block head
body
block content
+appMount
block defaultBody
+injectExtrasBody
+JS
block scriptsAnd can be extended like any other .pug template:
//- index.pug
//- include/extends ~%PATH% resolves to node_modules/%PATH%
extends ~html-webpack-template-pug/layout.pug
block head
link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css")
block content
header
h2 Header
main
+appMount
footer
h2 Footer
block scripts
script(src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.0/jquery.min.js")
script(src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js")An example of webpack configuration with a custom template extending the default:
{
// ...
plugins: [
new HtmlWebpackPlugin({
// Required
inject: false,
template: '!!pug-loader!index.pug',
// Optional
appMountId: 'app',
mobile: true,
title: 'My App'
// Other options...
})
]
}For more flexibility it is possible to directly include mixins.pug and then construct a custom template.
Available mixins are:
-
titleAdds title, to be used in
<head>. -
faviconAdds favicon, to be used in
<head>. -
mobileAdds mobile meta tag, to be used in
<head>. -
appMount(ids)Adds a div tag for each supplied id
@idscan be an Array or a single id, if none supplied uses appMountId;
also accepts attributes to be added to div tags,+appMount("id")(class="mount-point"). -
injectExtrasHeadInjects extra resources passed in
injectExtras.headofhtmlWebpackPlugin.options. -
injectExtrasBodyInjects extra resources passed in
injectExtras.bodyofhtmlWebpackPlugin.options. -
inline(filename, tag, searchWithin)Inlines a resource in a tag
@filenameis a string or a RegExp to be compared against files passed in HtmlWebpackPlugin (htmlWebpackPlugin.files);
@tagif not provided is deduced from file extension
@searchWithin-- array of filenames to match against RegExp@filename,
equals to [...css, ...js] fromhtmlWebpackPlugin.filesby default;
also accepts attributes to be added to style/script tags,+inline(...)(attributes). -
inject(filename, tag, searchWithin)Injects a resource in a tag
@filenameis a string or a RegExp to be compared againsthtmlWebpackPlugin.files;
@tagif not provided is deduced from file extension
@searchWithin-- array of filenames to match against RegExp@filename,
equals to [...css, ...js] fromhtmlWebpackPlugin.filesby default;
also accepts attributes to be added to link/script tags,+inject(...)(attributes). -
inlineCSS(cssList)Inlines css resources from
htmlWebpackPlugin.files, except for already inlined or injected resources;
@cssListcan be a single filename string, RegExp or an array of them,
cssListstrings starting with "!" are skipped;
by defaultcssList-- all css files that are supposed to be inlined according tohtmlWebpackPlugin.options; also accepts attributes to be added to style tags,+inlineCSS(...)(attributes). -
injectCSS(cssList)Injects css resources from
htmlWebpackPlugin.files, except for already inlined or injected resources;
@cssListcan be a single filename string, RegExp or an array of them,
cssListstrings starting with "!" are skipped;
by defaultcssList-- all css files that are supposed to be injected according tohtmlWebpackPlugin.options; also accepts attributes to be added to link tags,+injectCSS(...)(attributes). -
inlineJS(jsList)Inlines js resources from
htmlWebpackPlugin.files, except for already inlined or injected resources;
@jsListcan be a single filename string, RegExp or an array of them,
jsListstrings starting with "!" are skipped;
by defaultjsList-- all js files that are supposed to be inlined according tohtmlWebpackPlugin.options; also accepts attributes to be added to script tags,+inlineJS(...)(attributes). -
injectJS(jsList)Injects js resources from
htmlWebpackPlugin.files, except for already inlined or injected resources;
@jsListcan be a single filename string, RegExp or an array of them,
jsListstrings starting with "!" are skipped;
by defaultjsList-- all js files that are supposed to be injected according tohtmlWebpackPlugin.options; also accepts attributes to be added to script tags,+injectJS(...)(attributes). -
inlineChunk(chunkNames, type)Inlines files of type
@typefrom chunk with@chunkNamename;
@chunkName- a valid chunk name fromhtmlWebpackPlugin.files.chunksor an array of names,
@type- can be "css" or "js", which inlines css or js files respectively, otherwise inlines both types; also accepts attributes to be added to style/script tags,+inlineChunk(...)(attributes). -
injectChunk(chunkNames, type)Injects files of type
@typefrom chunk with@chunkNamename;
@chunkName- a valid chunk name fromhtmlWebpackPlugin.files.chunksor an array of names,
@type- can be "css" or "js", which injects css or js files respectively, otherwise injects both types; also accepts attributes to be added to link/script tags,+injectChunk(...)(attributes). -
CSSInlines css resources from chunks passed in
htmlWebpackPlugin.options.inline
and injects the rest, in the order they appearhtmlWebpackPlugin.files; also accepts attributes to be added to link/style tags,+CSS(...)(attributes). -
JSInlines js resources from chunks passed in
htmlWebpackPlugin.options.inline
and injects the rest, in the order they appearhtmlWebpackPlugin.files; also accepts attributes to be added to script tags,+JS(...)(attributes).
inline*, inject*, CSS and JS mixins keep track of inlined and injected files, so no one file will appear twice. This allows for:
+inlineCSS("style.css")
//- style.css
//- ...
//- the rest
+CSSHowever, inline and inject mixins allow duplicates.
To clarify usage of different parameters in inlineCSS, injectCSS, inlineJS and injectJS:
+inlineCSS
//- inlines all css resources passed in HtmlWebpackPlugin (htmlWebpackPlugin.files.css)
+inlineCSS("style.css")
//- inlines style.css
+inlineCSS(/\.css$/)
//- inlines all /\.css$/ matches in htmlWebpackPlugin.files.css
+inlineCSS("!style.css")
//- inlines all resources from htmlWebpackPlugin.files.css except for style.css
+inlineCSS(["style1.css", "style2.css"])
//- inlines style1.css and style2.css
+inlineCSS([/\.css$/, "!style2.css"])
//- inlines all /\.css$/ matches except for style2.css
+inlineCSS(["!style1.css", "!style2.css"])
//- inlines all resources from htmlWebpackPlugin.files.css except for style1.css and style2.cssA custom template can then look like this:
//- index.pug
//- include/extends ~%PATH% resolves to node_modules/%PATH%
include ~html-webpack-template-pug/mixins.pug
doctype html
html(lang='en')
head
meta(charset='utf-8')
meta(http-equiv='X-UA-Compatible', content='IE=edge')
base(href="../assets/page.html")
+mobile
+title
//- injects all .css files
+inject(/\.css$/)
body
+appMount
//- injects all .js files
+inject(/\.js$/)An example of webpack configuration with a custom template including the default mixins:
{
// ...
plugins: [
new HtmlWebpackPlugin({
// Required
inject: false,
template: '!!pug-loader!index.pug',
// Optional
appMountId: 'app',
mobile: true,
title: 'My App'
// Other options...
})
]
}This software is licensed under MIT.