Native HTML | webpack

This guide shows how to use webpack's native HTML handling with experiments.html, and how to migrate an existing setup off html-loader and html-webpack-plugin.
Native HTML is stable and the recommended way to build pages in webpack 5.109.0 and later — it is on by default. The option keeps its experiments.html name until webpack v6 makes it unconditional. html-loader and html-webpack-plugin are deprecated.
On webpack 5.109.0 or later there is nothing to install: point an entry at a page, and webpack builds it — no html-webpack-plugin, no html-loader:
experiments.html defaults to 'auto', which turns the built-in support on as long as no module.rules entry already claims .html files. Set it to true yourself when you add such a rule, or to make .html resolve ahead of .js for imports written without an extension:
Either way, webpack understands .html files as first-class modules: it parses them itself instead of handing them to a loader.
"Built-in" means webpack does the work itself, with no loader or plugin in the chain. It replaces html-loader and html-webpack-plugin, both deprecated, without copying every option they had — options that a native build no longer needs are deliberately left out. The scope is exactly this:
So a project using html-webpack-plugin to scaffold a document around its bundles, or html-loader to import a partial, needs neither. A project that renders its page through an asynchronous template engine keeps that engine's loader; a plugin that hooked into html-webpack-plugin rewrites onto webpack's own hooks.
Since webpack 5.109.0 the option defaults to 'auto': built-in HTML support turns on unless a module.rules entry with a loader (or an explicit module type) already matches .html files. An existing html-loader setup therefore keeps working untouched, and you can migrate one rule at a time. experiments.futureDefaults resolves it to true.
Native HTML covers three separate jobs that used to need two different packages. Pick the one that matches your project — they can be combined.
Point entry at an .html file and webpack builds the page itself: every <script src>, <link rel="stylesheet">, <img src>, inline <style> and inline <script> becomes part of the module graph, and the emitted page has all of its URLs rewritten to the built (hashed) filenames.
This is the HTML-first model Vite and Parcel use: the page is the source of truth about which scripts and styles it needs, so there is no second list of entry points to keep in sync.
When experiments.html is set to true explicitly, .html is added to the default resolve.extensions ahead of the JavaScript extensions, so entry: './src' resolves ./src/index.html even when ./src/index.js exists. With the 'auto' default, .html is only a fallback after .js.
If you would rather keep a JavaScript entry and have webpack write the document for you, set output.html. Webpack generates one HTML file per non-HTML entrypoint and injects that entrypoint's initial JS and CSS chunks — including chunks shared through dependOn:
This is the part of html-webpack-plugin that scaffolds a document around your bundles. Set output.html to an object to configure the generated page.
Importing an .html file from JavaScript gives you the processed HTML as a string, with every asset reference resolved through webpack — the role html-loader has played for years:
An HTML module imported this way is not emitted as a standalone file by default; an HTML module used as an entry is. Override either with module.generator.html.extract.
By default the parser treats a known set of URL-bearing attributes as dependencies. Everything below is handled with no configuration:
Two rules make the JavaScript side predictable:
Non-JS script types (application/ld+json, importmap, …), data URIs, and <style> with a non-CSS type flow through unchanged.
An inline body whose lang names another language enters the module graph as a data: module typed as that language's files, so a Rule.mimetype rule runs its loader on it — and on no other <style> or <script> of the page:
<script lang="ts"> needs no rule when experiments.typescript handles text/typescript — by default on Node.js 22.6+ when no rule already handles .ts files. Otherwise register a loader for it, e.g. { mimetype: "text/typescript", use: "ts-loader" }. The compiled CSS goes through the CSS pipeline like any other <style>, so url() resolves relative to the page, and a body no rule matches is read as CSS or JavaScript, as before.
A lang webpack knows no media type for is typed text/x-<lang>: x- marks an unregistered subtype, so it never collides with a type webpack already handles (text/javascript, text/css, text/html). A lang that can't be a media type at all (spaces, symbols) leaves the body as plain CSS or JavaScript.
A string mimetype condition matches by prefix, so "text/x-scss" also matches lang="scss2". Use a regular expression to match exactly one language:
A data: module has no file path. Loaders see the page's directory as this.context, but a loader that locates files from this.resourcePath — as sass-loader, less-loader and stylus-loader currently do — can't resolve a relative @use / @import from an inline body, and sass-loader reads lang="sass" as SCSS unless its options ask for the indented syntax. Keep partial-importing styles in a stylesheet file.
<style type="text/less"> and <script type="text/typescript"> keep flowing through unchanged — only lang opts a body into a loader.
Put a webpackIgnore comment immediately before a tag to leave its URLs alone — useful for CDN assets or URLs a server rewrites at runtime:
The first <base href> in the document changes how the relative URLs after it are bundled:
A <base href="/"> copied from an html-webpack-plugin template therefore needs no change. To keep bundling the URLs of a page whose base points to another origin, put a webpackIgnore comment before the <base> tag itself; the browser still honors the tag, so the emitted URLs then resolve against that origin:
Before webp