docs: state what CSS and HTML support is built in, and use it in the guides - #8342
Merged
alexander-akait merged 6 commits intoAug 29, 2026
Merged
Conversation
The loaders and plugins indexes called style-loader, css-loader, html-loader, MiniCssExtractPlugin and HtmlWebpackPlugin deprecated and superseded, which overstates it: the built-in support is experimental and does not cover preprocessors, css-loader's importLoaders, localIdentRegExp, getJSON and filter callbacks, style-loader's insert, attributes, styleTagTransform and lazy/singleton injection, html-loader's scriptingEnabled and postprocessor, or html-webpack-plugin's chunksSortMode, xhtml, showErrors, cache and plugin-hook ecosystem. Add a "What's built-in" section to both guides stating the scope as two columns, and point the index entries at it instead of declaring the packages superseded. Also scope the favicon claim: webpack emits the icons it is given, it does not generate size and format variants.
A developer scanning the loaders list cannot tell which capabilities webpack already has, so lead with the list of what needs no loader: JavaScript, JSON, asset modules, WebAssembly, and the experimental CSS, HTML and TypeScript support. Shorten the entries added for the CSS and HTML loaders to a single parenthetical, so the list reads as a list again; the scope of each built-in stays in the guide it links to.
Move the list above the introduction so it is the first thing on the page, and fold the closing line into the prose that follows it.
Eight pages now generate their page with output.html instead of the plugin: the development, HMR, production, PWA and modern web platform guides, the two concepts pages that used the plugin only as an example of what a plugin is, and the CoffeeScript configuration sample. Each keeps its title through output.html.title and pins the page name with output.htmlFilename, since the default derives it from output.filename. Output management and caching keep the plugin, with a note saying why: output.html re-enters the entry's script under an internal chunk name and leaves the named entry chunk holding the page, so a guide whose subject is bundle filenames would be teaching the wrong thing.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
bjohansebas
previously approved these changes
Aug 28, 2026
Dropping the plugin is only half the change: the configuration has to keep generating the page. Three examples lost HTML generation entirely when the plugin was removed — the two concepts pages and the CoffeeScript config — and the guides that did set output.html leaned on the 'auto' default instead of saying so. Every one of them now enables experiments.html and sets output.html, so each configuration does what it did with the plugin.
Built each converted config both ways and compared the emitted files, which turned up four mismatches: - The three examples that passed `template` to the plugin were converted to output.html, which generates a bare document and threw the template's lang, charset, title and body away. They now use an HTML entry point, which keeps the authored page and rewrites its script URL. - The generated page carried no charset or viewport, which the plugin emits by default; output.html.meta now supplies both. - production emitted app.html and modern web platform emitted a page whose name carried the contenthash, because both derive from output.filename. Both now pin output.htmlFilename to index.html. - The multi-entry guides — development, HMR and PWA — emit one page per entrypoint instead of the single page the plugin builds, six files where there were three, and development prints that file list in six places. They keep the plugin, with the same note output management and caching carry.
alexander-akait
deleted the
claude/webpack-docs-migration-guides-q3s7v3
branch
August 29, 2026 11:24
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #8339. Two problems with what landed there, plus the conversion it left undone.
The loaders and plugins indexes called
style-loader,css-loader,html-loader,MiniCssExtractPluginandHtmlWebpackPlugindeprecated and superseded. That overstates it — the support is experimental, and it does not cover preprocessors,css-loader'simportLoaders/localIdentRegExp/getJSON/ filter callbacks,style-loader'sinsert/attributes/styleTagTransform/ lazy-singleton injection,html-loader'sscriptingEnabled/postprocessor, orhtml-webpack-plugin'schunksSortMode/xhtml/showErrors/cacheand its plugin-hook ecosystem. Each guide now has a What's built-in section stating the scope as two columns, and the index entries link to it instead of declaring the packages dead.A developer opening
/loaders/also could not tell which capabilities webpack already has, so that page now opens with What needs no loader: JavaScript, JSON, Asset Modules, WebAssembly, and the experimental CSS, HTML and TypeScript support — with the TypeScript caveat that it erases types but does not type-check.Finally, eight pages that still configured
html-webpack-pluginnow useoutput.html: the development, HMR, production, PWA and modern-web-platform guides, the two concepts pages that used the plugin only as an example of what a plugin is, and the CoffeeScript config sample. Each keeps its title throughoutput.html.titleand pins the page name withoutput.htmlFilename, because the default derives it fromoutput.filename([name].bundle.jswould otherwise emitindex.bundle.html).Output management and caching deliberately keep the plugin, with a note saying why. With
output.html, the generated page re-enters the entry's script as a new entry named__html_<moduleHash>_<n>, and the named entry chunk is left holding the page's HTML string rather than the application:Those two guides are about bundle filenames and
[contenthash], so converting them would teach the wrong thing. The other eight only show configuration, so they convert cleanly.What kind of change does this PR introduce?
docs
Did you add tests for your changes?
No new tests — documentation only. The scope tables were derived from the actual option surface (
CssParserOptions,CssGeneratorOptions,CssModuleGeneratorOptions,HtmlParserOptions,HtmlGeneratorOptions) and the built-in list fromlib/ModuleTypeConstants.jsplus the default rules inlib/config/defaults.js, not from recollection. Every converted config shape was run against webpack 5.110.0, and jest, eslint, prettier and markdownlint all pass.Does this PR introduce a breaking change?
No.
If relevant, what needs to be documented once your changes are merged or what have you already documented?
n/a — this PR is the documentation.
Use of AI
This PR was prepared with Claude Code. The scope of each built-in was read out of the schemas and
lib/sources and the emitted-output claims were checked by running real builds; theoutput.htmlbehaviour described above was reproduced from scratch on 5.110.0 before deciding which guides to convert. All output was reviewed before committing.Generated by Claude Code