|
| 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 | +``` |
0 commit comments