html-loader

library1.0.0jsnpmunverified

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.

web-framework data

npm install html-loader

github ↗package ↗

INSTALL

IMPORT

SIG · HTML-LOADER

html-loader

web-frameworkjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

✗ const HtmlLoader = require('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.

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, }, }, ], }, };

Debug

Known issues

breakingMinimum Node.js version changed to 18.12.0 in v5.0.0

fix

Upgrade Node.js to >=18.12.0

affects: >=5.0.0

breakingMinimum Node.js version changed to 14.15.0 in v4.0.0

fix

Upgrade Node.js to >=14.15.0

affects: >=4.0.0 <5.0.0

breakingparse5 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

affects: >=4.0.0

deprecatedThe 'interpolate' option was removed in v3.0.0; use 'preprocessor' instead

fix

Replace 'interpolate' with 'preprocessor' function

affects: >=3.0.0

gotchaBy 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

affects: >=1.0.0

gotchaWhen 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

affects: >=4.0.0

Errors

Common errors & fixes

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

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: Cannot find module 'html-loader'

html-loader not installed

fix

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

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

Invalid or misspelled option in html-loader configuration

fix

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

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

Using deprecated 'interpolate' option removed in v3.0.0

fix

Replace 'interpolate' with a 'preprocessor' function

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

webpackrequiredPeer dependency required for loader functionality

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/webpack-contrib/html-loader ↗

packagehttps://www.npmjs.com/package/html-loader ↗