html-webpack-plugin

html-webpack-plugin is the standard webpack plugin for generating the HTML files that load your bundled JavaScript and CSS. Instead of hand-editing script and link tags every time an output filename or content hash changes, the plugin watches the compilation’s chunks and entry points and injects the right tags automatically — with zero configuration needed for a simple single-page app.

Beyond the zero-config default, it supports custom EJS/Handlebars/Pug templates, per-entry filenames for multi-page builds, favicon handling, and a set of typed tapable hooks (beforeAssetTagGeneration, alterAssetTags, afterTemplateExecution, beforeEmit, and more) that let a large ecosystem of companion plugins — subresource integrity, CSP headers, favicon generation, asset inlining — extend its output without patching webpack itself.

What You Get

• Zero-config HTML generation for single-page apps — works immediately after new HtmlWebpackPlugin()
• Custom template support via EJS, Handlebars, Pug, or a raw loader for full control over markup
• Multi-page output with per-entry filename functions and chunks/excludeChunks filtering
• Automatic favicon copying and <link rel="icon"> injection
• Six ordered tapable hooks for deep customization by companion plugins
• Cached child compilation so unchanged output isn’t re-emitted on every rebuild

Common Use Cases

• Single-page app builds - front-end teams building an SPA get an index.html with correctly hashed script/link tags emitted automatically on every build, no manual editing needed.
• Multi-page/multi-entry sites - projects with several entry points use per-entry filename functions and chunks filtering to emit one HTML file per page from a single webpack config.
• Custom branded templates - teams with existing HTML templates (EJS, Handlebars, Pug) plug them in via template/templateContent to keep their own markup while still getting automatic asset injection.
• Building companion webpack plugins - plugin authors hook into beforeAssetTagGeneration, alterAssetTags, or beforeEmit to add SRI hashes, CSP meta tags, or inline critical CSS without forking core.

Under The Hood

Architecture The main HtmlWebpackPlugin class in index.js (~1,568 lines) hooks into webpack’s compiler via apply(compiler) and exposes six ordered tapable AsyncSeriesWaterfallHooks (beforeAssetTagGeneration, alterAssetTags, alterAssetTagGroups, afterTemplateExecution, beforeEmit, afterEmit) through a static getCompilationHooks() keyed off a WeakMap<Compilation, Hooks> so multiple plugin instances share one hook registry per compilation. Actual HTML generation is delegated to lib/cached-child-compiler.js and lib/child-compiler.js, which spin up a webpack child compiler using NodeTemplatePlugin/NodeTargetPlugin/LoaderTargetPlugin/EntryPlugin to compile the user’s template into a runnable module and execute it in a VM context to produce the final HTML string; lib/chunksorter.js orders entries in the output and lib/html-tags.js models the injected script/link/meta tags as reusable objects. Because the tapable hooks are the plugin’s entire public extension surface, a large ecosystem of downstream plugins (subresource-integrity, favicon, CSP plugins) depends directly on this child-compiler abstraction remaining stable.

Tech Stack Written as plain CommonJS JavaScript with @ts-check and a hand-authored typings.d.ts for consumer typing rather than being written in TypeScript directly, so the package ships raw source with no build/transpile step. Runtime dependencies are minimal and targeted: tapable for the hook system, lodash for template interpolation, html-minifier-terser for optional output minification, and pretty-error for readable compiler error output. webpack (^5.20) and @rspack/core are both declared as optional peer dependencies, reflecting a recent push to support Rspack alongside webpack. Tooling around the package is comprehensive: Jest for tests, ESLint + Prettier + cspell for linting, Husky/lint-staged/commitlint for commit hygiene, and standard-version for releases, all wired into GitHub Actions CI.

Code Quality Test coverage is extensive — spec/basic.spec.js alone runs to nearly 3,900 lines covering broad permutations of plugin options and output, alongside dedicated suites for incremental/watch caching (caching.spec.js), hot module replacement behavior (hot.spec.js), and an example-build regression suite that diffs generated output against fixtures using dir-compare. Errors are handled explicitly and formatted through a dedicated lib/errors.js module rather than swallowed, and every source file uses @ts-check with JSDoc type annotations checked against typings.d.ts via a posttest tsc run, giving most of the safety of TypeScript without a compile step. Naming is consistent and CI enforces lint plus the full test suite on every change.

API Design The public surface is intentionally small: a single constructor option object covers the common cases with sane defaults, so a bare new HtmlWebpackPlugin() works with no configuration at all. Options like chunks, excludeChunks, chunksSortMode, and a function-valued filename cover the large majority of multi-entry scenarios without needing to escape into hook code, while the six documented tapable hooks (mirrored in both a JSDoc block in index.js and the Hooks namespace in typings.d.ts) give advanced users typed, ordered extension points. This combination of a low floor and a well-documented, typed extension ceiling is what has let a wide ecosystem of independent companion plugins build on it without needing to fork or monkey-patch core behavior.