html-webpack-plugin: what to do now that webpack calls it deprecated

The problem html-webpack-plugin solves: hashed bundle filenames

A webpack build produces JavaScript files whose names change whenever their contents change, because the filename includes a content hash. Your index.html has to reference those exact names. Hand-maintaining that file means editing a script tag after every build, and a stale reference produces a blank page with a 404 in the console. The README describes the plugin as simplifying the creation of HTML files to serve webpack bundles, and singles out bundles that include a hash in the filename which changes every compilation. That is the specific pain it removes.

It is aimed at application authors, not library authors. If you publish a package that other people import, you have no HTML to generate. If you build a single-page app, a multi-page site, or a server-rendered template that needs the current bundle names injected, you are the target user. The README also notes the plugin works without configuration, which is why it shows up in zero-config webpack setups.

How the plugin decides what to inject

The plugin sits in webpack's compilation and reads the assets webpack emits, then writes an HTML file that references them. The README gives three ways to control the output: let the plugin generate the file, supply your own template using lodash templates, or use your own loader. The repository ships default_index.ejs at the top level and lists it in the published files array in package.json, so the default template is part of the package rather than something fetched at runtime.

The extension surface is a set of hooks. The README states the plugin provides hooks to extend it to your needs, and that several existing plugins integrate with zero configuration. The companion list in the README is the clearest picture of the design: webpack-subresource-integrity for asset security, favicons-webpack-plugin for icon generation, html-webpack-harddisk-plugin to always write the HTML file to disk when webpack-dev-server or HMR is in use, html-webpack-inline-svg-plugin to inline SVGs, and resource-hints-webpack-plugin to add preload and prefetch link tags. Each of those needs to see or modify the HTML at a defined moment, and the hook list is what makes that possible. If you write your own plugin against those hooks, you are depending on an interface the deprecation notice does not promise to keep.

Installing html-webpack-plugin and generating a first page

The README splits installation by webpack major version. For webpack 5, install the current package:

npm i --save-dev html-webpack-plugin

The yarn equivalent given in the README is `yarn add --dev html-webpack-plugin`. For webpack 4, the README pins the major version instead:

npm i --save-dev html-webpack-plugin@4

That distinction matters. The version in the repository's package.json is 5.6.8, and the README does not describe 5.x as compatible with webpack 4. Getting this wrong is one likely source of the module resolution errors people search for.

The README states the plugin works without configuration, so the minimum is adding it to the plugins array. The repository's examples directory is where working configurations live: it contains default, custom-template, multi-page, inline, favicon, pug-loader, html-loader, custom-insertion-position, sort-manually, chunk-optimization, template-parameters, and javascript-advanced examples, and examples/build-examples.js builds them. After a build you should find an HTML file in your output directory with script tags pointing at the emitted bundle filenames. The README does not document the full option list in the excerpt available here, so treat the examples rather than a guessed option list as the reference.

The deprecation notice is the main limitation

The README opens with a warning that html-webpack-plugin is deprecated, stating that webpack scaffolds the HTML around your bundles itself and no longer needs it, and pointing to the Native HTML guide and its migration section. That is the single most important fact about this project right now, and it changes the decision from "which HTML plugin" to "do I need one at all."

The practical consequence is narrower than the word deprecated suggests. The same notice says existing setups keep working, because webpack only emits a page when you ask for one with output.html. So the plugin keeps owning your HTML until you migrate. Nothing breaks on upgrade day.

The real exposure is the hook interface. Plugins such as favicons-webpack-plugin, html-webpack-harddisk-plugin, and webpack-subresource-integrity integrate through the plugin's hooks, per the README. A migration to webpack's native HTML has to reproduce whatever those plugins were doing at those hook points. The README does not document rollback, and it does not describe a compatibility layer for hook consumers, so the migration path for a project with three or four HTML-adjacent plugins is not something this repository answers.

One more boundary: the plugin generates an HTML file. It does not compile your templates into components, manage routing, or handle server-side rendering. If your pages are produced by a framework's own build step, this is the wrong layer to reach for.

webpack's native output.html as the alternative

The alternative named by the project itself is webpack's built-in HTML output. The difference in approach is ownership: instead of a plugin that hooks into the compilation and writes a file, webpack emits the page directly, controlled by the output.html configuration key. There is no plugin instance in your config and no hook pipeline to attach to.

That is a smaller surface, and it is the direction the README points to. It is also less extensible by construction. The README's list of companion plugins exists because people needed to modify the generated HTML at specific moments: injecting integrity attributes, inlining SVGs, adding resource hints, forcing writes to disk under webpack-dev-server. A native emitter has to offer equivalent extension points for those use cases to move over, and the excerpt here does not say how it does. Anyone whose config depends on two or more of those plugins should read the migration guide before assuming the switch is a one-line config change.

For a plain single-page build with no HTML-adjacent plugins, the native path removes a dependency and a version-pinning problem. For a build with a custom loader-based template, the trade-off is less obvious.

Maintenance, version pinning and the MIT licence

The repository is not archived, and the last push was on 2026-09-07. The published version in package.json is 5.6.8, and the recent release list is old: 2.29.0 from 2017, v2.0.3 from 2015, v2.0.0 from 2015. Those entries do not reflect the current 5.x line, so treat them as historical tags rather than the release cadence of the project today.

Upgrade cost has two parts. First, the webpack major version decides which plugin major you install, and the README gives separate commands for webpack 5 and webpack 4. Second, the deprecation notice means the eventual upgrade is not a plugin upgrade at all: it is a move to webpack's native HTML output, which the README frames as a migration with its own guide. Budget for that as a separate piece of work, and check your other plugins' hook usage first.

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. That is permissive and standard for webpack ecosystem packages. It tells you nothing about whether the project will keep receiving fixes once webpack's native path is the default; the README's own warning is the better signal there. This is a description of the licence terms, not legal advice.

Editorial conclusion

Adopt html-webpack-plugin if you are on webpack 4 or 5 with a working template, multiple entry points, or plugins that hook into its event pipeline, because the README states existing setups keep working and webpack only emits a page when output.html is configured. Do not adopt it for a new webpack 5 project, since the README marks it deprecated and points to the Native HTML guide and its migration section. Before committing, verify which version your project needs (5.6.8 is the version in package.json, while webpack 4 users are told to install html-webpack-plugin@4), and check whether any of your other plugins depend on its hooks, because that is the part a migration has to replace.

Frequently asked questions

Official sources

1. Issues
2. jantimon/html-webpack-plugin on GitHub
3. License: MIT
4. README
5. Releases