Exports HTML as string. HTML is minimized when the compiler demands.
To begin, you'll need to install html-loader:
npm install --save-dev html-loaderThen 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', }, ], }, };| Name | Type | Default | Description |
|---|---|---|---|
preprocessor | {Function} | undefined | Allows pre-processing of content before handling |
attributes | {Boolean\/Array\/Object} | true | Enables/Disables attributes handling |
root | {String} | undefiend | Allow to handle root-relative attributes |
minimize | {Boolean|Object} | true in production mode, otherwise false | Tell html-loader to minimize HTML |
esModule | {Boolean} | false | Use ES modules syntax |
Type: Function Default: undefined
Allows pre-processing of content before handling.
âš You should always return valid HTML
file.hbs
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; }, }, }, ], }, };Type: Boolean|Array|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:
audio:srcembed:srcimg:srcimg:srcsetinput:srclink:hrefobject:datascript:srcsource:srcsource:srcsettrack:srcvideo:postervideo:src
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: { // Disables tags and attributes processing attributes: false, }, }, ], }, };Allows you to specify which tags and attributes to process. Pass an array of <tag>:<attribute> or :<attribute> combinations. You can specify which tag-attribute combination should be processed by this loader via the query parameter attributes, for example:
webpack.config.js
module.exports = { module: { rules: [ { test: /\.html$/i, loader: 'html-loader', options: { attributes: [':data-src', 'custom-elements:data-src'], }, }, ], }, };Allows you to specify which tags and attributes to process, filter them and process sources starts with /. For example:
webpack.config.js
module.exports = { module: { rules: [ { test: /\.html$/i, loader: 'html-loader', options: { attributes: { list: [':data-src', 'custom-elements:data-src'], filter: (attribute, value, resourcePath) => { // The `attribute` argument contains a name of the HTML attribute. // The `value` argument contains a value of the HTML attribute. // The `resourcePath` argument contains a path to the loaded HTML file. if (value.includes('example')) { return false; } return true; }, root: '.', }, }, }, ], }, };Type: String Default: https://github.com/webpack-contrib/html-loader#attributes
For example:
webpack.config.js
module.exports = { module: { rules: [ { test: /\.html$/i, loader: 'html-loader', options: { attributes: { list: [':data-src', 'custom-elements:data-src'], }, }, }, ], }, };Type: Function Default: undefined
Allow to filter sources. All filtered sources 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: { filter: (attribute, value, resourcePath) => { // The `attribute` argument contains a name of the HTML attribute. // The `value` argument contains a value of the HTML attribute. // The `resourcePath` argument contains a path to the loaded HTML file. if (value.includes('example')) { return false; } return true; }, }, }, }, ], }, };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: '.', }, }, }, ], }, };Type: Boolean|Object Default: true in production mode, otherwise false
Tell html-loader to minimize HTML.
The enabled rules for minimizing by default are the following ones:
collapseWhitespaceconservativeCollapsekeepClosingSlashminifyCSSminifyJSremoveAttributeQuotesremoveCommentsremoveScriptTypeAttributesremoveStyleTypeAttributesuseShortDoctype
webpack.config.js
module.exports = { module: { rules: [ { test: /\.html$/i, loader: 'html-loader', options: { minimize: true, }, }, ], }, };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, }, }, }, ], }, };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, }, }, ], }, };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.png" data-src="image2x.png" />require('html-loader!./file.html'); // => '<img src="http://cdn.example.com/49eba9f/a992ca.png" data-src="image2x.png">'require('html-loader?attributes[]=img:data-src!./file.html'); // => '<img src="image.png" data-src="data:image/png;base64,..." >'require('html-loader?attributes[]=img:src&attributes[]=img:data-src!./file.html'); // => '<img src="http://cdn.example.com/49eba9f/a992ca.png" data-src="data:image/png;base64,..." >'require('html-loader?-attributes!./file.html'); // => '<img src="image.jpg" data-src="image2x.png" >'
⚠️ -attributesit is set attributes: false
'<img src=http://cdn.example.com/49eba9f/a9f92ca.jpg data-src=data:image/png;base64,...>'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', }, ], }, };With the same configuration as above:
file.html
<img src="/image.jpg" />scripts.js
require('html-loader!./file.html'); // => '<img src="/image.jpg">'other-scripts.js
require('html-loader?root=.!./file.html'); // => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg">'You can use any template system. Below is an example for handlebars.
file.hbs
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 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: () => { let result; try { result = posthtml() .use(plugin) .process(content, { sync: true }); } catch (error) { loaderContext.emitError(error); return content; } return result.html; }, }, }, ], }, };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:
- file-loader
- extract-loader
- html-loader
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'], }, ], }, };Please take a moment to read our contributing guidelines if you haven't yet done so.
