html-loader
Exports HTML as string. HTML is minimized when the compiler demands.
Getting Started
To begin, you'll need to install html-loader
:
npm install --save-dev html-loader
Then add the plugin to your webpack
config. For example:
file.js
import html from './file.html';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
},
],
},
};
Options
Name | Type | Default | Description |
---|
attributes | {Boolean|Object} | true | Enables/Disables attributes handling |
preprocessor | {Function} | undefined | Allows pre-processing of content before handling |
minimize | {Boolean|Object} | true in production mode, otherwise false | Tell html-loader to minimize HTML |
esModule | {Boolean} | false | Use ES modules syntax |
attributes
Type: Boolean|Object
Default: true
By default every loadable attributes (for example - <img src="image.png">
) is imported (const img = require('./image.png')
or import img from "./image.png""
).
You may need to specify loaders for images in your configuration (recommended file-loader
or url-loader
).
Supported tags and attributes:
- the
src
attribute of the audio
tag - the
src
attribute of the embed
tag - the
src
attribute of the img
tag - the
srcset
attribute of the img
tag - the
src
attribute of the input
tag - the
href
attribute of the link
tag (only for stylesheets) - the
data
attribute of the object
tag - the
src
attribute of the script
tag - the
src
attribute of the source
tag - the
srcset
attribute of the source
tag - the
src
attribute of the track
tag - the
poster
attribute of the video
tag - the
src
attribute of the video
tag
Boolean
The true
value enables processing of all default elements and attributes, the false
disable processing of all attributes.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: false,
},
},
],
},
};
Object
Allows you to specify which tags and attributes to process, filter them, filter urls and process sources starts with /
.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: {
list: [
{
tag: 'img',
attribute: 'src',
type: 'src',
},
{
tag: 'img',
attribute: 'srcset',
type: 'srcset',
},
{
tag: 'img',
attribute: 'data-src',
type: 'src',
},
{
tag: 'img',
attribute: 'data-srcset',
type: 'srcset',
},
{
tag: 'link',
attribute: 'href',
type: 'src',
filter: (tag, attribute, attributes) => {
if (!/stylesheet/i.test(attributes.rel)) {
return false;
}
if (
attributes.type &&
attributes.type.trim().toLowerCase() !== 'text/css'
) {
return false;
}
return true;
},
},
],
urlFilter: (attribute, value, resourcePath) => {
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
root: '.',
},
},
},
],
},
};
list
Type: Array
Default: https://github.com/webpack-contrib/html-loader#attributes
Allows to setup which tags and attributes to process and how, and the ability to filter some of them.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: {
list: [
{
tag: 'img',
attribute: 'src',
type: 'src',
},
{
tag: 'img',
attribute: 'srcset',
type: 'srcset',
},
{
tag: 'img',
attribute: 'data-src',
type: 'src',
},
{
tag: 'img',
attribute: 'data-srcset',
type: 'srcset',
},
{
tag: 'link',
attribute: 'href',
type: 'src',
filter: (tag, attribute, attributes, resourcePath) => {
if (/my-html\.html$/.test(resourcePath)) {
return false;
}
if (!/stylesheet/i.test(attributes.rel)) {
return false;
}
if (
attributes.type &&
attributes.type.trim().toLowerCase() !== 'text/css'
) {
return false;
}
return true;
},
},
],
},
},
},
],
},
};
If the tag name is not specified it will process all the tags.
You can use your custom filter to specify html elements to be processed.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: {
list: [
{
attribute: 'src',
type: 'src',
filter: (tag, attribute, attributes, resourcePath) => {
return tag.toLowerCase() !== 'img';
},
},
],
},
},
},
],
},
};
urlFilter
Type: Function
Default: undefined
Allow to filter urls. All filtered urls will not be resolved (left in the code as they were written).
All non requestable sources (for example <img src="javascript:void(0)">
) do not handle by default.
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: {
urlFilter: (attribute, value, resourcePath) => {
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
},
},
},
],
},
};
root
Type: String
Default: undefined
For urls that start with a /
, the default behavior is to not translate them.
If a root
query parameter is set, however, it will be prepended to the url and then translated.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
attributes: {
root: '.',
},
},
},
],
},
};
preprocessor
Type: Function
Default: undefined
Allows pre-processing of content before handling.
⚠ You should always return valid HTML
file.hbs
<div>
<p>{{firstname}} {{lastname}}</p>
<img src="image.png" alt="alt" />
<div>
Function
You can set the preprocessor
option as a Function
instance.
webpack.config.js
const Handlebars = require('handlebars');
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: 'html-loader',
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = Handlebars.compile(content)({
firstname: 'Value',
lastname: 'OtherValue',
});
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
You can also set the preprocessor
option as an asynchronous function instance.
For example:
webpack.config.js
const Handlebars = require('handlebars');
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: 'html-loader',
options: {
preprocessor: async (content, loaderContext) => {
let result;
try {
result = await Handlebars.compile(content)({
firstname: 'Value',
lastname: 'OtherValue',
});
} catch (error) {
await loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
minimize
Type: Boolean|Object
Default: true
in production mode, otherwise false
Tell html-loader
to minimize HTML.
Boolean
The enabled rules for minimizing by default are the following ones:
({
caseSensitive: true,
collapseWhitespace: true,
conservativeCollapse: true,
keepClosingSlash: true,
minifyCSS: true,
minifyJS: true,
removeComments: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true,
});
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
minimize: true,
},
},
],
},
};
Object
webpack.config.js
See html-minifier-terser's documentation for more information on the available options.
The rules can be disabled using the following options in your webpack.conf.js
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
minimize: {
removeComments: false,
collapseWhitespace: false,
},
},
},
],
},
};
esModule
Type: Boolean
Default: false
By default, html-loader
generates JS modules that use the CommonJS modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.
You can enable a ES module syntax using:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
esModule: true,
},
},
],
},
};
Examples
CDN
webpack.config.js
module.exports = {
module: {
rules: [
{ test: /\.jpg$/, loader: 'file-loader' },
{ test: /\.png$/, loader: 'url-loader' },
],
},
output: {
publicPath: 'http://cdn.example.com/[hash]/',
},
};
file.html
<img src="image.jpg" data-src="image2x.png" />
index.js
require('html-loader!./file.html');
require('html-loader?{"attributes":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
require('html-loader?{"attributes":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
require('html-loader?-attributes!./file.html');
:warning: -attributes
sets attributes: false
.
Process script
and link
tags
script.file.js
console.log(document);
style.file.css
a {
color: red;
}
file.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Title of the document</title>
<link rel="stylesheet" type="text/css" href="./style.file.css" />
</head>
<body>
Content of the document......
<script src="./script.file.js"></script>
</body>
</html>
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
use: ['file-loader?name=[name].[ext]', 'extract-loader', 'html-loader'],
},
{
test: /\.js$/i,
exclude: /\.file.js$/i,
loader: 'babel-loader',
},
{
test: /\.file.js$/i,
loader: 'file-loader',
},
{
test: /\.css$/i,
exclude: /\.file.css$/i,
loader: 'css-loader',
},
{
test: /\.file.css$/i,
loader: 'file-loader',
},
],
},
};
'Root-relative' URLs
With the same configuration as in the CDN example:
file.html
<img src="/image.jpg" />
scripts.js
require('html-loader!./file.html');
other-scripts.js
require('html-loader?{"attributes":{"root":"."}}!./file.html');
Templating
You can use any template system. Below is an example for handlebars.
file.hbs
<div>
<p>{{firstname}} {{lastname}}</p>
<img src="image.png" alt="alt" />
<div>
webpack.config.js
const Handlebars = require('handlebars');
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: 'html-loader',
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = Handlebars.compile(content)({
firstname: 'Value',
lastname: 'OtherValue',
});
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result;
},
},
},
],
},
};
PostHTML
You can use PostHTML without any additional loaders.
file.html
<img src="image.jpg" />
webpack.config.js
const posthtml = require('posthtml');
const posthtmlWebp = require('posthtml-webp');
module.exports = {
module: {
rules: [
{
test: /\.hbs$/i,
loader: 'html-loader',
options: {
preprocessor: (content, loaderContext) => {
let result;
try {
result = posthtml().use(plugin).process(content, { sync: true });
} catch (error) {
loaderContext.emitError(error);
return content;
}
return result.html;
},
},
},
],
},
};
Export into HTML files
A very common scenario is exporting the HTML into their own .html file, to
serve them directly instead of injecting with javascript. This can be achieved
with a combination of 3 loaders:
The html-loader will parse the URLs, require the images and everything you
expect. The extract loader will parse the javascript back into a proper html
file, ensuring images are required and point to proper path, and the file loader
will write the .html file for you. Example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
use: ['file-loader?name=[name].[ext]', 'extract-loader', 'html-loader'],
},
],
},
};
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
License
MIT