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 |
---|
sources | {Boolean|Object} | true | Enables/Disables sources 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} | true | Enable/disable ES modules syntax |
sources
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 asset modules
).
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
data
attribute of the object
tag - the
src
attribute of the script
tag - the
href
attribute of the script
tag - the
xlink:href
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 - the
xlink:href
attribute of the image
tag - the
href
attribute of the image
tag - the
xlink:href
attribute of the use
tag - the
href
attribute of the use
tag - the
href
attribute of the link
tag when the rel
attribute contains stylesheet
, icon
, shortcut icon
, mask-icon
, apple-touch-icon
, apple-touch-icon-precomposed
, apple-touch-startup-image
, manifest
, prefetch
, preload
or when the itemprop
attribute is image
, logo
, screenshot
, thumbnailurl
, contenturl
, downloadurl
, duringmedia
, embedurl
, installurl
, layoutimage
- the
imagesrcset
attribute of the link
tag when the rel
attribute contains stylesheet
, icon
, shortcut icon
, mask-icon
, apple-touch-icon
, apple-touch-icon-precomposed
, apple-touch-startup-image
, manifest
, prefetch
, preload
- the
content
attribute of the meta
tag when the name
attribute is msapplication-tileimage
, msapplication-square70x70logo
, msapplication-square150x150logo
, msapplication-wide310x150logo
, msapplication-square310x310logo
, msapplication-config
, twitter:image
or when the property
attribute is og:image
, og:image:url
, og:image:secure_url
, og:audio
, og:audio:secure_url
, og:video
, og:video:secure_url
, vk:image
or when the itemprop
attribute is image
, logo
, screenshot
, thumbnailurl
, contenturl
, downloadurl
, duringmedia
, embedurl
, installurl
, layoutimage
- the
icon-uri
value component in content
attribute of the meta
tag when the name
attribute is msapplication-task
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: {
sources: 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: {
sources: {
list: [
'...',
{
tag: 'img',
attribute: 'data-src',
type: 'src',
},
{
tag: 'img',
attribute: 'data-srcset',
type: 'srcset',
},
],
urlFilter: (attribute, value, resourcePath) => {
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
},
},
},
],
},
};
list
Type: Array
Default: supported tags and attributes.
Allows to setup which tags and attributes to process and how, and the ability to filter some of them.
Using ...
syntax allows you to extend default supported tags and attributes.
For example:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
sources: {
list: [
'...',
{
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: {
sources: {
list: [
{
attribute: 'src',
type: 'src',
filter: (tag, attribute, attributes, resourcePath) => {
return tag.toLowerCase() !== 'img';
},
},
],
},
},
},
],
},
};
Filter can also be used to extend the supported elements and attributes.
For example, filter can help process meta tags that reference assets:
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
sources: {
list: [
{
tag: 'meta',
attribute: 'content',
type: 'src',
filter: (tag, attribute, attributes, resourcePath) => {
if (
attributes.value === 'og:image' ||
attributes.name === 'twitter:image'
) {
return true;
}
return false;
},
},
],
},
},
},
],
},
};
Note: source with a tag
option takes precedence over source without.
Filter can be used to disable default sources.
For example:
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
sources: {
list: [
'...',
{
tag: 'img',
attribute: 'src',
type: 'src',
filter: () => false,
},
],
},
},
},
],
},
};
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: {
sources: {
urlFilter: (attribute, value, resourcePath) => {
if (/example\.pdf$/.test(value)) {
return false;
}
return true;
},
},
},
},
],
},
};
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: true
By default, html-loader
generates JS modules that use the ES 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 CommonJS modules syntax using:
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {
esModule: false,
},
},
],
},
};
Examples
With <!-- webpackIgnore: true -->
comment, can to disable sources handling for next tag.
<img src="image.png" />
<img
srcset="image.png 480w, image.png 768w"
src="image.png"
alt="Elva dressed as a fairy"
/>
<meta itemprop="image" content="./image.png" />
<link rel="icon" type="image/png" sizes="192x192" href="./image.png" />
roots
With resolve.roots
can specify a list of directories where requests of server-relative URLs (starting with '/') are resolved.
webpack.config.js
module.exports = {
context: __dirname,
module: {
rules: [
{
test: /\.html$/i,
loader: 'html-loader',
options: {},
},
{
test: /\.jpg$/,
type: 'asset/resource',
},
],
},
resolve: {
roots: [path.resolve(__dirname, 'fixtures')],
},
};
file.html
<img src="/image.jpg" />
CDN
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.jpg$/,
type: 'asset/resource',
},
{
test: /\.png$/,
type: 'asset/inline',
},
],
},
output: {
publicPath: 'http://cdn.example.com/[fullhash]/',
},
};
file.html
<img src="image.jpg" data-src="image2x.png" />
index.js
require('html-loader!./file.html');
require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
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$/,
type: 'asset/resource',
generator: {
filename: '[name][ext]',
},
},
{
test: /\.html$/i,
use: ['extract-loader', 'html-loader'],
},
{
test: /\.js$/i,
exclude: /\.file.js$/i,
loader: 'babel-loader',
},
{
test: /\.file.js$/i,
type: 'asset/resource',
},
{
test: /\.css$/i,
exclude: /\.file.css$/i,
loader: 'css-loader',
},
{
test: /\.file.css$/i,
type: 'asset/resource',
},
],
},
};
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 2 loaders:
and asset modules
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 asset modules
will write the .html file for you. Example:
webpack.config.js
module.exports = {
output: {
assetModuleFilename: '[name][ext]',
},
module: {
rules: [
{
test: /\.html$/,
type: 'asset/resource',
generator: {
filename: '[name][ext]',
},
},
{
test: /\.html$/i,
use: ['extract-loader', 'html-loader'],
},
],
},
};
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
License
MIT