html-replace-webpack-plugin

2.6.0 verified Sat Apr 25 auth: no javascript maintenance

A Webpack plugin that replaces HTML content during build using string or regex patterns. Currently at version 2.6.0 with a low release cadence (last update in 2019). It works exclusively with html-webpack-plugin, processing the output of that plugin. Allows single or multiple replacement rules with string or function replacements. Lightweight alternative to heavier string replacement tasks in Webpack. Only tested with Webpack 4.x; no support for Webpack 5 or ESM.

Common errors

error TypeError: HtmlReplaceWebpackPlugin is not a constructor ↓

cause Correctly importing as default but often caused by spelling or named import.

fix

const HtmlReplaceWebpackPlugin = require('html-replace-webpack-plugin');

error The 'pattern' property is required for each replacement object. ↓

cause Passing an empty object or missing pattern field.

fix

Ensure each object has a 'pattern' and 'replacement' property.

error HtmlWebpackPlugin is not defined ↓

cause Missing installation or require of html-webpack-plugin.

fix

npm i -D html-webpack-plugin; then require it before use.

error Cannot find module 'html-replace-webpack-plugin' ↓

cause Plugin not installed or not in node_modules.

fix

npm i -D html-replace-webpack-plugin

Warnings

breaking html-webpack-plugin must be placed before html-replace-webpack-plugin in plugins array (Webpack 4). ↓

fix Ensure HtmlWebpackPlugin is instantiated before HtmlReplaceWebpackPlugin in the plugins array.

gotcha Plugin only processes HTML generated by html-webpack-plugin; not standalone HTML files. ↓

fix Use html-webpack-plugin and ensure it processes the target HTML files.

gotcha Named import or destructured require fails: const { HtmlReplaceWebpackPlugin } = require(...) => TypeError: HtmlReplaceWebpackPlugin is not a constructor. ↓

fix Use default require: const HtmlReplaceWebpackPlugin = require('html-replace-webpack-plugin').

deprecated Last release 2.6.0 (2019); no Webpack 5 support; may break with newer versions. ↓

fix Consider alternatives like string-replace-loader or custom hooks for Webpack 5.

gotcha Passing multiple rules as separate arguments (e.g., new Plugin(rule1, rule2)) fails; only first rule processed. ↓

fix Wrap rules in an array: new Plugin([rule1, rule2]).

Install

npm install html-replace-webpack-plugin

yarn add html-replace-webpack-plugin

pnpm add html-replace-webpack-plugin

Imports

default

wrong

import HtmlReplaceWebpackPlugin from 'html-replace-webpack-plugin'

correct

const HtmlReplaceWebpackPlugin = require('html-replace-webpack-plugin')

Package is CJS only; ESM import will fail. Use require() in Webpack config.

HtmlReplaceWebpackPlugin

wrong

const { HtmlReplaceWebpackPlugin } = require('html-replace-webpack-plugin')

correct

const HtmlReplaceWebpackPlugin = require('html-replace-webpack-plugin')

Plugin is exported as a single default function, not a named export. Named destructuring returns undefined.

Plugin usage
wrong
```
new HtmlReplaceWebpackPlugin({ pattern: 'foo', replacement: 'bar' })
```
correct
```
new HtmlReplaceWebpackPlugin([{ pattern: 'foo', replacement: 'bar' }])
```
Passing a single object instead of an array works (accepts either), but passing multiple arguments as separate objects fails. Use array for multiple rules.

Quickstart

Shows how to configure html-replace-webpack-plugin with html-webpack-plugin to replace HTML comments with CDN links for CSS/JS.

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');
const HtmlReplaceWebpackPlugin = require('html-replace-webpack-plugin');

const resource = {
  js: { bootstrap: '//cdn/bootstrap/bootstrap.min.js' },
  css: { bootstrap: '//cdn/bootstrap/bootstrap.min.css' },
  img: { 'the-girl': '//cdn/img/the-girl.jpg' }
};

const tpl = {
  img: '<img src="%s">',
  css: '<link rel="stylesheet" type="text/css" href="%s">',
  js: '<script type="text/javascript" src="%s"></script>'
};

module.exports = {
  entry: './src/index.js',
  plugins: [
    new HtmlWebpackPlugin({
      title: 'My App',
      template: './src/index.html'
    }),
    new HtmlReplaceWebpackPlugin([
      { pattern: 'foo', replacement: 'bar' },
      { pattern: '@@title', replacement: 'My App' },
      {
        pattern: /(<!--\s*|@@)(css|js|img):([\w-\/]+)(\s*-->)?/g,
        replacement: function(match, $1, type, file, $4, index, input) {
          var url = resource[type][file];
          return $4 == undefined ? url : tpl[type].replace('%s', url);
        }
      }
    ])
  ]
};