Skip to content

Commit 8559d11

Browse files
feat: add the SSR manifest and collect server styles without a DOM
A server render puts a lazy route's markup in the document long before the browser asks for the chunk carrying that route's stylesheet, so the page arrives unstyled. Two additive, opt-in primitives close that: - `SSRManifestPlugin` emits `ssr-manifest.json`, mapping each source module to the client assets it needs — its chunk, the splits loaded with it and the async ancestors it is reached through — so a server injects `modulepreload` and stylesheet tags for exactly what it rendered. Stylesheets are listed in the order they cascade, the rule the extracted HTML already writes them by. - The CSS runtimes collect styles on a document-less target (`target: "node"`), not only behind a runtime check on a universal bundle, so `__webpack_css_server_styles__` answers in a dedicated server build. A worker keeps the DOM path: it has no `fs` to read a stylesheet with. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01K8n6KpLAPpLZdLrovcDnAu
1 parent b6ccff1 commit 8559d11

64 files changed

Lines changed: 1582 additions & 54 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"webpack": minor
3+
---
4+
5+
Add `SSRManifestPlugin`, emitting a source-module to client-asset manifest whose stylesheets are listed in cascade order, and collect server styles on document-less targets such as `target: "node"`.

‎cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,7 @@
372372
"rotatey",
373373
"rotatez",
374374
"rowspan",
375+
"rsbuild",
375376
"rspack",
376377
"rrggbb",
377378
"rrggbbaa",
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/*
2+
* This file was automatically generated.
3+
* DO NOT MODIFY BY HAND.
4+
* Run `yarn fix:special` to update
5+
*/
6+
7+
export interface SSRManifestPluginOptions {
8+
/**
9+
* The base directory used to compute the source-module keys (defaults to the compiler context).
10+
*/
11+
context?: string;
12+
/**
13+
* Specifies the filename of the emitted manifest on disk. By default the plugin will emit `ssr-manifest.json` inside the 'output.path' directory.
14+
*/
15+
filename?: string;
16+
}

‎examples/ssr/README.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
# Server-Side Rendering (SSR)
2+
3+
Two builds from one source tree — a browser bundle and a Node bundle that renders the same route to HTML — using the SSR building blocks webpack provides:
4+
5+
| Feature | What it does |
6+
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
7+
| `SSRManifestPlugin` | Emits `ssr-manifest.json`: source module → the client files needed to run it, so the server can preload exactly what it rendered. |
8+
| `ManifestPlugin` | Emits `manifest.json`: emitted asset → its source, plus the entrypoint graph, for asset pipelines and backend templating. |
9+
| `__webpack_css_server_styles__` | The CSS collected while rendering without a DOM, ready to inline as critical CSS. |
10+
| `externalsPresets: { node, nodeModules }` | Keeps node builtins and installed packages out of the server bundle; `allowlist` bundles individual packages anyway. |
11+
| `generator: { emit: false }` | The server build resolves asset URLs without writing the files a second time — the client build already emitted them. |
12+
| `generator.css.exportsOnly` | Defaults to `true` on a document-less target, so a server build emits no stylesheets at all; set it to `false` to write them anyway. |
13+
| `import.meta.env.*` | `SSR` is `true` in this `target: "node"` build and `false` in the client one, so server-only branches leave the browser bundle. Also `MODE` / `DEV` / `PROD` / `BASE_URL`. |
14+
15+
The server build targets `node`, so webpack knows there is no DOM: `import.meta.env.SSR` folds to `true`, and the CSS runtime collects the styles instead of linking them into a page. It opts back into emitting stylesheets (`exportsOnly: false`) only because the collected CSS is read back from them; leave the default on and the server build writes no CSS at all.
16+
17+
# example.js
18+
19+
```javascript
20+
import "./style.css";
21+
22+
if (import.meta.env.DEV) {
23+
console.log("client bundle, mode:", import.meta.env.MODE);
24+
}
25+
26+
// `page.js` is code-split; the SSR manifest maps it to the client assets
27+
// (its JS chunk and CSS) to preload when it is rendered on the server.
28+
import("./page.js").then(({ render }) => {
29+
document.body.innerHTML = render();
30+
});
31+
```
32+
33+
# page.js
34+
35+
```javascript
36+
import "./page.css";
37+
38+
export function render() {
39+
return '<h1 class="headline">Hello from server-side rendering</h1>';
40+
}
41+
```
42+
43+
# server.js
44+
45+
```javascript
46+
import { readFileSync } from "node:fs";
47+
48+
// The Node half of the app: it renders the route to HTML and consumes the
49+
// client build's artifacts. Read once at startup; re-read per request if the
50+
// client is rebuilt while the server is running.
51+
const manifest = JSON.parse(
52+
readFileSync("dist/client/ssr-manifest.json", "utf8")
53+
);
54+
55+
export async function renderDocument() {
56+
// The route is code-split, so only its modules load here — and only their
57+
// CSS ends up in the collected styles below.
58+
const { render } = await import("./page.js");
59+
const body = render();
60+
61+
// CSS collected while rendering without a DOM. `SSR` is `true` only in a
62+
// node build, so this branch is dropped from the browser bundle entirely.
63+
const criticalCss = import.meta.env.SSR ? __webpack_css_server_styles__ : "";
64+
65+
// Exactly the client files the rendered module needs, including the chunks
66+
// it depends on — without them the browser would discover them one round
67+
// trip too late.
68+
const files = manifest["./page.js"] || [];
69+
const tags = files
70+
.map((file) =>
71+
file.endsWith(".css")
72+
? `<link rel="stylesheet" href="${file}">`
73+
: `<link rel="modulepreload" href="${file}">`
74+
)
75+
.join("");
76+
77+
return `<!doctype html>
78+
<html>
79+
<head>
80+
${tags}
81+
<style>${criticalCss}</style>
82+
</head>
83+
<body>${body}</body>
84+
</html>`;
85+
}
86+
```
87+
88+
# webpack.config.js
89+
90+
```javascript
91+
"use strict";
92+
93+
const path = require("path");
94+
const webpack = require("../../");
95+
96+
/** @type {import("webpack").Configuration} */
97+
const client = {
98+
name: "client",
99+
target: "web",
100+
entry: "./example.js",
101+
output: {
102+
path: path.resolve(__dirname, "dist/client"),
103+
filename: "[name].js",
104+
// baked into the manifests, so the server emits URLs it never has to rewrite
105+
publicPath: "/dist/client/"
106+
},
107+
optimization: {
108+
chunkIds: "named" // keep filenames stable across modes (for this example)
109+
},
110+
plugins: [
111+
// source module -> the client files needed to run it, for the server to preload
112+
new webpack.SSRManifestPlugin(),
113+
// emitted asset -> its source, plus the entrypoint graph, for asset pipelines
114+
new webpack.ManifestPlugin()
115+
]
116+
};
117+
118+
/** @type {import("webpack").Configuration} */
119+
const server = {
120+
name: "server",
121+
// a node target has no DOM, so `import.meta.env.SSR` is `true` here and the
122+
// CSS runtime collects the styles rather than linking them into a page
123+
target: "node",
124+
entry: "./server.js",
125+
output: {
126+
path: path.resolve(__dirname, "dist/server"),
127+
filename: "[name].mjs",
128+
chunkFilename: "[name].mjs",
129+
library: { type: "module" }
130+
},
131+
// keep node builtins and installed packages out of the server bundle; add
132+
// `allowlist` to bundle individual packages anyway (ESM-only ones, say)
133+
externalsPresets: { node: true, nodeModules: true },
134+
module: {
135+
rules: [
136+
{
137+
test: /\.(png|jpe?g|svg|woff2?)$/,
138+
type: "asset/resource",
139+
// the client build already wrote these files; only the URL is needed here
140+
generator: { emit: false }
141+
}
142+
],
143+
generator: {
144+
css: {
145+
// a document-less target emits no stylesheets by default; opt in,
146+
// because the collected CSS below is read back from them
147+
exportsOnly: false
148+
}
149+
}
150+
},
151+
optimization: {
152+
chunkIds: "named"
153+
},
154+
experiments: {
155+
outputModule: true
156+
}
157+
};
158+
159+
module.exports = [client, server];
160+
```
161+
162+
# dist/client/ssr-manifest.json
163+
164+
Keyed by source module. `./page.js` lists its own chunk, its CSS, and any chunk it depends on.
165+
166+
```json
167+
{
168+
"./example.js": [
169+
"/dist/client/main.js",
170+
"/dist/client/main.css"
171+
],
172+
"./page.css": [
173+
"/dist/client/page_js.js",
174+
"/dist/client/page_js.css"
175+
],
176+
"./page.js": [
177+
"/dist/client/page_js.js",
178+
"/dist/client/page_js.css"
179+
],
180+
"./style.css": [
181+
"/dist/client/main.js",
182+
"/dist/client/main.css"
183+
]
184+
}
185+
```
186+
187+
# dist/client/manifest.json
188+
189+
Keyed by emitted asset, with the entrypoint graph alongside it.
190+
191+
```json
192+
{
193+
"entrypoints": {
194+
"main": {
195+
"imports": [
196+
"main.js",
197+
"main.css"
198+
]
199+
}
200+
},
201+
"assets": {
202+
"main.js": {
203+
"file": "/dist/client/main.js"
204+
},
205+
"main.css": {
206+
"file": "/dist/client/main.css"
207+
},
208+
"page_js.js": {
209+
"file": "/dist/client/page_js.js"
210+
},
211+
"page_js.css": {
212+
"file": "/dist/client/page_js.css"
213+
}
214+
}
215+
}
216+
```
217+
218+
# Info
219+
220+
## Unoptimized
221+
222+
```
223+
client:
224+
assets by path *.js 15.1 KiB
225+
asset main.js 14.3 KiB [emitted] (name: main)
226+
asset page_js.js 820 bytes [emitted]
227+
assets by path *.json 721 bytes
228+
asset manifest.json 389 bytes [emitted]
229+
asset ssr-manifest.json 332 bytes [emitted]
230+
assets by path *.css 243 bytes
231+
asset main.css 122 bytes [emitted] (name: main)
232+
asset page_js.css 121 bytes [emitted]
233+
Entrypoint main 14.4 KiB = main.js 14.3 KiB main.css 122 bytes
234+
chunk (runtime: main) main.js, main.css (main) 343 bytes (javascript) 35 bytes (css) 8.78 KiB (runtime) [entry] [rendered]
235+
> ./example.js main
236+
runtime modules 8.78 KiB 10 modules
237+
dependent modules 35 bytes [dependent] 1 module
238+
./example.js 343 bytes [built] [code generated]
239+
[no exports]
240+
[used exports unknown]
241+
entry ./example.js main
242+
chunk (runtime: main) page_js.js, page_js.css 121 bytes (javascript) 37 bytes (css) [rendered]
243+
> ./page.js ./example.js 9:0-19
244+
dependent modules 37 bytes [dependent] 1 module
245+
./page.js 121 bytes [built] [code generated]
246+
[exports: render]
247+
[used exports unknown]
248+
import() ./page.js ./example.js 9:0-19
249+
client (webpack X.X.X) compiled successfully
250+
251+
server:
252+
asset main.mjs 11.6 KiB [emitted] [javascript module] (name: main)
253+
asset page_js.mjs 822 bytes [emitted] [javascript module]
254+
asset page_js.css 121 bytes [emitted]
255+
chunk (runtime: main) main.mjs (main) 1.33 KiB (javascript) 5.33 KiB (runtime) [entry] [rendered]
256+
> ./server.js main
257+
runtime modules 5.33 KiB 8 modules
258+
dependent modules 42 bytes [dependent] 1 module
259+
./server.js 1.29 KiB [built] [code generated]
260+
[exports: renderDocument]
261+
[used exports unknown]
262+
entry ./server.js main
263+
used as library export
264+
chunk (runtime: main) page_js.mjs, page_js.css 121 bytes (javascript) 37 bytes (css) [rendered]
265+
> ./page.js ./server.js 13:26-45
266+
dependent modules 37 bytes [dependent] 1 module
267+
./page.js 121 bytes [built] [code generated]
268+
[exports: render]
269+
[used exports unknown]
270+
import() ./page.js ./server.js 13:26-45
271+
server (webpack X.X.X) compiled successfully
272+
```
273+
274+
## Production mode
275+
276+
```
277+
client:
278+
assets by path *.js 3.24 KiB
279+
asset main.js 3.04 KiB [emitted] [minimized] (name: main)
280+
asset page_js-page_css.js 200 bytes [emitted] [minimized]
281+
assets by path *.json 793 bytes
282+
asset manifest.json 425 bytes [emitted]
283+
asset ssr-manifest.json 368 bytes [emitted]
284+
assets by path *.css 49 bytes
285+
asset main.css 28 bytes [emitted] [minimized] (name: main)
286+
asset page_js-page_css.css 21 bytes [emitted] [minimized]
287+
Entrypoint main 3.07 KiB = main.js 3.04 KiB main.css 28 bytes
288+
chunk (runtime: main) main.js, main.css (main) 385 bytes (javascript) 35 bytes (css) 8.58 KiB (runtime) [entry] [rendered]
289+
> ./example.js main
290+
runtime modules 8.58 KiB 9 modules
291+
cacheable modules 385 bytes (javascript) 35 bytes (css)
292+
./example.js + 1 modules 385 bytes [built] [code generated]
293+
[no exports]
294+
[no exports used]
295+
entry ./example.js main
296+
css ./style.css 35 bytes [built] [code generated]
297+
[no exports]
298+
[no exports used]
299+
chunk (runtime: main) page_js-page_css.js, page_js-page_css.css 163 bytes (javascript) 37 bytes (css) [rendered]
300+
> ./page.js ./example.js 9:0-19
301+
./page.js + 1 modules 163 bytes [built] [code generated]
302+
[exports: render]
303+
[all exports used]
304+
import() ./page.js ./example.js + 1 modules ./example.js 9:0-19
305+
css ./page.css 37 bytes [built] [code generated]
306+
[no exports]
307+
[no exports used]
308+
client (webpack X.X.X) compiled successfully
309+
310+
server:
311+
asset main.mjs 2.3 KiB [emitted] [javascript module] [minimized] (name: main)
312+
asset page_js-page_css.mjs 207 bytes [emitted] [javascript module] [minimized]
313+
asset page_js-page_css.css 21 bytes [emitted] [minimized]
314+
chunk (runtime: main) main.mjs (main) 1.33 KiB (javascript) 5.15 KiB (runtime) [entry] [rendered]
315+
> ./server.js main
316+
runtime modules 5.15 KiB 7 modules
317+
./server.js + 1 modules 1.33 KiB [not cacheable] [built] [code generated]
318+
[exports: renderDocument]
319+
[all exports used]
320+
entry ./server.js main
321+
used as library export
322+
chunk (runtime: main) page_js-page_css.mjs, page_js-page_css.css 163 bytes (javascript) 37 bytes (css) [rendered]
323+
> ./page.js ./server.js 13:26-45
324+
./page.js + 1 modules 163 bytes [built] [code generated]
325+
[exports: render]
326+
[all exports used]
327+
import() ./page.js ./server.js + 1 modules ./server.js 13:26-45
328+
css ./page.css 37 bytes [built] [code generated]
329+
[no exports]
330+
[no exports used]
331+
server (webpack X.X.X) compiled successfully
332+
```

‎examples/ssr/build.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
global.NO_TARGET_ARGS = true;
2+
global.NO_PUBLIC_PATH = true;
3+
require("../build-common");

‎examples/ssr/example.js‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import "./style.css";
2+
3+
if (import.meta.env.DEV) {
4+
console.log("client bundle, mode:", import.meta.env.MODE);
5+
}
6+
7+
// `page.js` is code-split; the SSR manifest maps it to the client assets
8+
// (its JS chunk and CSS) to preload when it is rendered on the server.
9+
import("./page.js").then(({ render }) => {
10+
document.body.innerHTML = render();
11+
});

‎examples/ssr/page.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.headline {
2+
color: rebeccapurple;
3+
}

‎examples/ssr/page.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import "./page.css";
2+
3+
export function render() {
4+
return '<h1 class="headline">Hello from server-side rendering</h1>';
5+
}

0 commit comments

Comments
 (0)