Skip to content

Commit 01e4d99

Browse files
docs: build the front page example with native HTML and CSS
The splash example bundled one JavaScript file and asked the reader to write the page by hand, pointing a <script> tag at dist/bundle.js. Webpack handles all three now, so the example starts from src/index.html: the page links a stylesheet and a script, entry points at the page, and the emitted document is shown next to the config with its URLs rewritten to the hashed assets. Verified against webpack 5.110.3 — an HTML entry turns on the html and css support on its own, and htmlFilename keeps the page's name out of the contenthash pattern. The migration guide's companion-plugin table now covers the popular html-webpack-plugin ecosystem rather than five entries, and a new section maps its six hooks onto HtmlModulesPlugin's, with a plugin rewritten through transformTags and injectTags as the worked example. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NuWDbcF2jvq7q1r8aEY5V9
1 parent 831bc3f commit 01e4d99

7 files changed

Lines changed: 112 additions & 44 deletions

File tree

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
1-
**src/index.js**
1+
**src/index.html**
22

3-
```js
4-
import bar from "./bar.js";
5-
6-
bar();
3+
```html
4+
<!doctype html>
5+
<html lang="en">
6+
<head>
7+
<meta charset="utf-8" />
8+
<title>My App</title>
9+
<link rel="stylesheet" href="./styles.css" />
10+
</head>
11+
<body>
12+
<script type="module" src="./index.js"></script>
13+
</body>
14+
</html>
715
```
Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
1-
**src/bar.js**
1+
**src/index.js**
22

33
```js
4-
export default function bar() {
5-
//
4+
import bar from "./bar.js";
5+
6+
bar();
7+
```
8+
9+
**src/styles.css**
10+
11+
```css
12+
body {
13+
font-family: system-ui;
614
}
715
```
Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,16 @@
1-
Start without a configuration file, or provide a custom **webpack.config.js**:
1+
Point webpack at the page in **webpack.config.js**:
22

33
```js
4-
import path from "node:path";
5-
import { fileURLToPath } from "node:url";
6-
7-
const __filename = fileURLToPath(import.meta.url);
8-
const __dirname = path.dirname(__filename);
9-
104
export default {
11-
entry: "./src/index.js",
5+
entry: "./src/index.html",
126
output: {
13-
path: path.resolve(__dirname, "dist"),
14-
filename: "bundle.js",
7+
filename: "[contenthash].js",
8+
cssFilename: "[contenthash].css",
9+
htmlFilename: "[name].html",
1510
},
1611
};
1712
```
1813

19-
Prefer a video walkthrough? **[Without config](https://youtu.be/3Nv9muOkb6k?t=21293)**
14+
Webpack parses the page, bundles everything it references, and rewrites the URLs. No loader, no plugin.
15+
16+
Prefer a video walkthrough? **[Watch one here](https://youtu.be/3Nv9muOkb6k?t=21293)**
Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
**page.html**
1+
**dist/index.html**
22

33
```html
4-
<!DOCTYPE html>
5-
<html>
4+
<!doctype html>
5+
<html lang="en">
66
<head>
77
<meta charset="utf-8" />
8-
...
8+
<title>My App</title>
9+
<link rel="stylesheet" href="725d71b1a0d330cfd1ad.css" />
910
</head>
1011
<body>
11-
...
12-
<script src="dist/bundle.js"></script>
12+
<script src="91b32a0aad9e59b71d57.js"></script>
1313
</body>
1414
</html>
1515
```

‎src/components/SplashViz/SplashViz.jsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ export default function SplashViz() {
1313
<span> scripts </span>
1414
<span> images </span>
1515
<span> styles </span>
16+
<span> pages </span>
1617
</TextRotator>
1718
</h1>
1819
<div

‎src/content/guides/native-html.mdx‎

Lines changed: 71 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,14 @@ With this option enabled, webpack understands `.html` files as first-class modul
3030

3131
"Built-in" means webpack does the work itself, with no loader or plugin in the chain — not that it covers everything `html-loader` and `html-webpack-plugin` do. The scope is exactly this:
3232

33-
| Built in | Still needs a loader or plugin |
34-
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
35-
| Parsing `.html`, as an [entry point](#1-html-as-an-entry-point) or [imported from JS](#3-html-imported-from-javascript) | **Template engines** — Pug, EJS, Handlebars and friends, unless a synchronous [`template`](#templating) hook is enough |
36-
| [Extracting every URL a page references](#what-webpack-bundles-from-a-page) and rewriting it to the built filename | `html-loader`'s `sources.scriptingEnabled` and `postprocessor` |
37-
| Bundling inline `<script>` and `<style>` bodies, and `style=""` attributes | `html-webpack-plugin`'s `chunksSortMode`, `xhtml`, `showErrors` and `cache` |
38-
| [Generating a page](#2-a-generated-page-for-a-javascript-entry) per entrypoint with its chunks injected | The third-party plugins that tap `html-webpack-plugin`'s hooks, which have no counterpart on [`HtmlModulesPlugin`](#plugin-hooks) yet |
39-
| [`title`, `meta`, `base`, `favicon`, `manifest`, `integrity`, `csp`, inlining](#configuring-the-generated-page) | |
40-
| [Minification](#minification) and Hot Module Replacement | |
33+
| Built in | Still needs a loader or plugin |
34+
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35+
| Parsing `.html`, as an [entry point](#1-html-as-an-entry-point) or [imported from JS](#3-html-imported-from-javascript) | **Template engines** — Pug, EJS, Handlebars and friends, unless a synchronous [`template`](#templating) hook is enough |
36+
| [Extracting every URL a page references](#what-webpack-bundles-from-a-page) and rewriting it to the built filename | `html-loader`'s `sources.scriptingEnabled` and `postprocessor` |
37+
| Bundling inline `<script>` and `<style>` bodies, and `style=""` attributes | `html-webpack-plugin`'s `chunksSortMode`, `xhtml`, `showErrors` and `cache` |
38+
| [Generating a page](#2-a-generated-page-for-a-javascript-entry) per entrypoint with its chunks injected | The third-party plugins that tap `html-webpack-plugin`'s hooks — they do not run as-is, but most [rewrite](#rewriting-a-plugin-that-tapped-its-hooks) into a few lines |
39+
| [`title`, `meta`, `base`, `favicon`, `manifest`, `integrity`, `csp`, inlining](#configuring-the-generated-page) | |
40+
| [Minification](#minification) and Hot Module Replacement | |
4141

4242
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 a template engine, or depends on a plugin that hooks into `html-webpack-plugin`, keeps that plugin.
4343

@@ -647,15 +647,22 @@ T> While `experiments.html` is `'auto'` (the default since 5.109.0), a `module.r
647647
| `cache`, `showErrors`, `xhtml` | n/a |
648648
| plugin hooks | [`HtmlModulesPlugin` hooks](#plugin-hooks) |
649649
650-
Companion plugins fold in too:
651-
652-
| Plugin | Native equivalent |
653-
| ----------------------------------- | ------------------------------------------------------------------------ |
654-
| `html-webpack-inline-source-plugin` | [`output.html.inline`](#inlining-critical-chunks) |
655-
| `webpack-subresource-integrity` | [`output.html.integrity`](#subresource-integrity-and-csp) |
656-
| `csp-html-webpack-plugin` | [`output.html.csp`](#subresource-integrity-and-csp) |
657-
| `preload-webpack-plugin` | [`output.resourceHints`](#resource-hints) |
658-
| `favicons-webpack-plugin` | [`output.html.favicon` / `manifest`](#favicons-and-the-web-app-manifest) |
650+
Companion plugins fold in too. Most of the popular ones are an option now; the rest are a few lines against the [`HtmlModulesPlugin` hooks](#rewriting-a-plugin-that-tapped-its-hooks):
651+
652+
| Plugin | Instead |
653+
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
654+
| `html-webpack-inline-source-plugin` | [`output.html.inline`](#inlining-critical-chunks), or a `<!-- webpackInline: true -->` comment on the tag |
655+
| `webpack-subresource-integrity` | [`output.html.integrity`](#subresource-integrity-and-csp) |
656+
| `csp-html-webpack-plugin`, `strict-csp-html-webpack-plugin` | [`output.html.csp`](#subresource-integrity-and-csp) |
657+
| `preload-webpack-plugin`, `resource-hints-webpack-plugin`, `html-webpack-inject-preload` | [`output.resourceHints`](#resource-hints), or the [`webpackPreload` / `webpackPrefetch`](#magic-comments) comments |
658+
| `favicons-webpack-plugin` | [`output.html.favicon` / `manifest`](#favicons-and-the-web-app-manifest) |
659+
| `html-webpack-injector` | [`output.html.inject`](/configuration/output/#outputhtmlinject), or put the tag where you want it in an HTML entry |
660+
| `html-webpack-include-assets-plugin` | write the tag in the page; mark files copied verbatim with `<!-- webpackIgnore: true -->` |
661+
| `html-webpack-exclude-assets-plugin`, `html-webpack-skip-assets-plugin` | nothing — a page carries what it references, and an entry opts out of a generated page with the descriptor `html: false` |
662+
| `html-webpack-harddisk-plugin` | [`devServer.devMiddleware.writeToDisk`](/configuration/dev-server/#devserverdevmiddleware) |
663+
| `html-webpack-inject-attributes-plugin`, `webpack-nomodule-plugin`, `html-webpack-link-type-plugin` | the [`transformTags`](#rewriting-a-plugin-that-tapped-its-hooks) hook |
664+
| `inject-body-webpack-plugin`, `html-webpack-inline-style-plugin`, `html-webpack-inline-svg-plugin` | write it in the page, or the [`transformHtml`](#rewriting-a-plugin-that-tapped-its-hooks) hook |
665+
| `appcache-webpack-plugin` | n/a — AppCache was removed from browsers |
659666
660667
### Without a template
661668
@@ -791,6 +798,53 @@ export default {
791798
792799
Each page pulls in exactly the chunks it references, so `chunks` / `excludeChunks` have nothing left to do. The same works with generated pages — `output.html: true` plus one JavaScript entry per page.
793800
801+
### Rewriting a plugin that tapped its hooks
802+
803+
A plugin written against `html-webpack-plugin` does not run without it, but the hook it used has a counterpart on [`HtmlModulesPlugin`](#plugin-hooks):
804+
805+
| `html-webpack-plugin` | `HtmlModulesPlugin` |
806+
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
807+
| `beforeAssetTagGeneration` | n/a — the tags come from the page and the chunk graph, so there is no asset list to edit up front |
808+
| `alterAssetTags`, `alterAssetTagGroups` | [`transformTags`](/api/compilation-hooks/#transformtags) to change, remove or move existing tags, [`injectTags`](/api/compilation-hooks/#injecttags) to add new ones |
809+
| `afterTemplateExecution` | [`module.parser.html.template`](#templating) |
810+
| `beforeEmit` | [`transformHtml`](/api/compilation-hooks/#transformhtml) |
811+
| `afterEmit` | [`htmlEmitted`](/api/compilation-hooks/#htmlemitted) |
812+
813+
Both plugins hand you the hooks per compilation, so the shape of the plugin barely changes — swap `HtmlWebpackPlugin.getCompilationHooks(compilation)` for `compiler.webpack.html.HtmlModulesPlugin.getCompilationHooks(compilation)` and work with tag descriptors instead of the plugin's `assetTags`:
814+
815+
```js
816+
class NoModulePlugin {
817+
apply(compiler) {
818+
compiler.hooks.compilation.tap("NoModulePlugin", (compilation) => {
819+
const hooks =
820+
compiler.webpack.html.HtmlModulesPlugin.getCompilationHooks(
821+
compilation,
822+
);
823+
824+
// alterAssetTags: mutate what is already on the page
825+
hooks.transformTags.tap("NoModulePlugin", (tags) => {
826+
for (const tag of tags) {
827+
if (tag.tag === "script") {
828+
tag.attrs.nomodule = true;
829+
}
830+
}
831+
});
832+
833+
// beforeAssetTagGeneration: add tags of your own
834+
hooks.injectTags.tap("NoModulePlugin", (tags) => {
835+
tags.push({
836+
tag: "meta",
837+
attrs: { name: "theme-color", content: "#2b3a42" },
838+
});
839+
return tags;
840+
});
841+
});
842+
}
843+
}
844+
```
845+
846+
`transformTags` mutates in place (`attrs`, `remove: true`, `injectTo`), while `injectTags` and `transformHtml` are waterfalls — return the value you were given. Anything that only rewrites the final markup, such as inlining styles or injecting a snippet into `<body>`, is a one-line `transformHtml` tap.
847+
794848
## All options with examples
795849
796850
HTML is configured in four places: the [parser](#parser-options) and [generator](#generator-options) under `module`, the [output options](#output-options) that describe the emitted page, and the [minimizer](#minifier-options) options under `optimization`. The tables below list every option, with the reference entry linked from each name.

‎src/content/index.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ import Install from "../components/Splash/install/install.mdx";
3939
</div>
4040
</div>
4141

42-
Then run `webpack` on the command-line to create `bundle.js`.
42+
Then run `webpack` on the command-line: HTML, CSS and JavaScript are all handled by webpack itself, so `dist/` ends up with the page and the hashed assets it points at.
4343

4444
## Awesome, isn't it? Let's dive in!
4545

46-
**[Get Started](/guides/getting-started)** quickly in our **Guides** section, or dig into the **[Concepts](/concepts)** section for more high-level information on the core notions behind webpack.
46+
**[Get Started](/guides/getting-started)** quickly in our **Guides** section, or dig into the **[Concepts](/concepts)** section for more high-level information on the core notions behind webpack. The [Native HTML](/guides/native-html/) and [Native CSS](/guides/native-css/) guides cover what the built-in support does, and how to migrate an existing setup onto it.

0 commit comments

Comments
 (0)