html-loader

5.1.0 verified Sat Apr 25 auth: no javascript

Webpack loader that exports HTML as a string, automatically resolving and processing references to assets like images, scripts, and stylesheets. Current stable release is v5.1.0 (July 2024), with breaking changes in v5.0.0 (Node.js >=18.12.0 required) and v4.0.0 (Node.js >=14.15.0, updated parse5). Key differentiators: supports sources configuration for custom tag/attribute handling, preprocessor and postprocessor hooks, and integrates with webpack's asset modules. Actively maintained under webpack-contrib, with frequent updates and community support.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Missing html-loader rule in webpack config for .html files

fix

Add { test: /\.html$/i, loader: 'html-loader' } to module.rules in webpack.config.js

error Error: Cannot find module 'html-loader' ↓

cause html-loader not installed

fix

Run 'npm install --save-dev html-loader' or 'yarn add -D html-loader'

error ValidationError: Invalid options object. HTML Loader has been initialized using an options object that does not match the API schema. ↓

cause Invalid or misspelled option in html-loader configuration

fix

Check the options object matches the documented schema (sources, preprocessor, postprocessor, minimize, esModule)

error Error: 'interpolate' option is not supported. Use 'preprocessor' instead. ↓

cause Using deprecated 'interpolate' option removed in v3.0.0

fix

Replace 'interpolate' with a 'preprocessor' function

Warnings

breaking Minimum Node.js version changed to 18.12.0 in v5.0.0 ↓

fix Upgrade Node.js to >=18.12.0

breaking Minimum Node.js version changed to 14.15.0 in v4.0.0 ↓

fix Upgrade Node.js to >=14.15.0

breaking parse5 updated to v7.0.0 in v4.0.0, may cause different parsing behavior ↓

fix Test HTML parsing with new parse5 version; adjust HTML if needed

deprecated The 'interpolate' option was removed in v3.0.0; use 'preprocessor' instead ↓

fix Replace 'interpolate' with 'preprocessor' function

gotcha By default, html-loader imports all loadable asset attributes (e.g., img src). Ensure you have appropriate loaders for those assets, such as asset modules. ↓

fix Configure asset modules or file-loader for referenced assets

gotcha When using 'sources.urlFilter', the filter function receives the attribute name, value, and resource path. Remember that the 'value' may be a relative path. Use resourcePath to resolve correctly. ↓

fix Use path.resolve(path.dirname(resourcePath), value) if needed

Install

npm install html-loader

yarn add html-loader

pnpm add html-loader

Imports

default

wrong

const HtmlLoader = require('html-loader');

correct

module.exports = { module: { rules: [ { test: /\.html$/i, loader: 'html-loader' } ] } };

No JavaScript symbol is exported; use as a webpack loader string.

default import in webpack config
```
import HtmlLoader from 'html-loader';
```
ESM import is valid for webpack config files using ESM, but the loader is used as a string in rules.
require in webpack config
```
const HtmlLoader = require('html-loader');
```
CommonJS require works in webpack config; the loader can be referenced as a string.

Quickstart

Configures html-loader in webpack to process HTML files, resolve image sources, and minimize output.

// webpack.config.js
const path = require('path');

module.exports = {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: 'html-loader',
        options: {
          sources: {
            list: [
              {
                tag: 'img',
                attribute: 'src',
                type: 'src',
              },
            ],
            urlFilter: (attribute, value, resourcePath) => {
              // Only process .png files
              return /\.png$/i.test(value);
            },
          },
          minimize: true,
        },
      },
    ],
  },
};