HTML Webpack Plugin

5.6.7 verified Sat Apr 25 auth: no javascript

Plugin that simplifies creation of HTML files to serve your webpack bundles, especially useful for bundles with hashed filenames. Current stable version: 5.6.7. The plugin generates an HTML file for you, or you can provide your own template using lodash templates. It injects all webpack bundles into the HTML and supports a rich event system for extensibility. Key differentiators: zero-config setup, hooks for custom plugins, and support for multiple HTML files. Alternatives like HtmlBundlerPlugin or script-ext-html-webpack-plugin build on top of this. Actively maintained with frequent releases.

Common errors

error Error: HtmlWebpackPlugin: could not load file: /path/to/template.html ↓

cause Template path is incorrect or file does not exist.

fix

Ensure 'template' option points to an existing file. Use absolute path or relative to webpack context.

error Module not found: Error: Can't resolve 'html-webpack-plugin' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install --save-dev html-webpack-plugin' or 'yarn add --dev html-webpack-plugin'.

error TypeError: HtmlWebpackPlugin is not a constructor ↓

cause Incorrect import: used named import instead of default.

fix

Use default import: 'import HtmlWebpackPlugin from 'html-webpack-plugin'' or 'const HtmlWebpackPlugin = require('html-webpack-plugin')'.

Warnings

breaking Version 5 requires webpack ^5.20.0. Using with webpack 4 requires version 4 of the plugin. ↓

fix If using webpack 4, install html-webpack-plugin@4. For webpack 5, ensure webpack ^5.20.0.

gotcha The plugin replaces the entire body content by default. To avoid removing existing content, use 'inject' option. ↓

fix Set 'inject' to 'head' or 'body' explicitly, or use a custom template with manual injection.

deprecated The 'compilation' event hooks are deprecated in favor of the new hook system in webpack 5. ↓

fix Migrate to using 'htmlWebpackPluginAlterAssetTags' or other new hooks.

gotcha If you use 'chunks' option, only those chunks are included. Omitting 'chunks' includes all chunks by default. ↓

fix Be explicit with 'chunks' option to avoid unexpected bundles. Use 'excludeChunks' to exclude specific ones.

gotcha Minification can corrupt HTML if not configured properly. Default minification uses html-minifier-terser. ↓

fix Configure 'minify' option or set to false. Known issue: removing quotes or collapsing boolean attributes may break certain elements.

Install

npm install html-webpack-plugin

yarn add html-webpack-plugin

pnpm add html-webpack-plugin

Imports

HtmlWebpackPlugin

wrong

const HtmlWebpackPlugin = require('html-webpack-plugin')

correct

import HtmlWebpackPlugin from 'html-webpack-plugin'

Default export. ESM works in Node 12+ with webpack. CJS via require also works.

HtmlWebpackPlugin

const HtmlWebpackPlugin = require('html-webpack-plugin')

CommonJS require is also supported.

HtmlWebpackPlugin

wrong

new require('html-webpack-plugin')()

correct

const HtmlWebpackPlugin = require('html-webpack-plugin'); module.exports.plugins.push(new HtmlWebpackPlugin())

Instantiate after import. Do not call require directly in constructor.

Quickstart

Basic webpack config using HtmlWebpackPlugin with a custom template and output filename.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'My App',
      template: './src/template.html'
    })
  ]
};