Skip to content

Commit 273fb24

Browse files
snitin315snitin315
authored
docs(configuration): dev-server v5 changes (#7144)
1 parent 3aea515 commit 273fb24

File tree

1 file changed

+35
-256
lines changed

1 file changed

+35
-256
lines changed

‎src/content/configuration/dev-server.mdx

Lines changed: 35 additions & 256 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ contributors:
2727

2828
[webpack-dev-server](https://github.com/webpack/webpack-dev-server) can be used to quickly develop an application. See the [development guide](/guides/development/) to get started.
2929

30-
This page describes the options that affect the behavior of webpack-dev-server (short: dev-server) <Badge text="version >= 4.0.0" />. Migration guide from `v3` to `v4` can be found [here](https://github.com/webpack/webpack-dev-server/blob/master/migration-v4.md).
30+
This page describes the options that affect the behavior of webpack-dev-server (short: dev-server) <Badge text="version >= 5.0.0" />. Migration guide from `v4` to `v5` can be found [here](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md).
3131

32-
W> `webpack-dev-server v4.0.0+` requires `node >= v12.13.0`, `webpack >= v4.37.0` (but we recommend using `webpack >= v5.0.0`), and `webpack-cli >= v4.7.0`.
32+
W> `webpack-dev-server v5.0.0+` requires `node >= v18.12.0`, `webpack >= v5.0.0` and `webpack-cli >= v4.7.0`, we recommend using the latest version.
3333

3434
## devServer
3535

@@ -461,7 +461,7 @@ module.exports = {
461461
Usage via the CLI:
462462

463463
```bash
464-
npx webpack serve --client-web-socket-transport ws --web-socket-server ws
464+
npx webpack serve --client-web-socket-transport ws --web-socket-server-type ws
465465
```
466466

467467
T> When providing a custom client and server implementation make sure that they are compatible with one another to communicate successfully.
@@ -607,148 +607,6 @@ module.exports = {
607607
};
608608
```
609609

610-
## devServer.http2
611-
612-
`boolean`
613-
614-
Serve over HTTP/2 using [spdy](https://www.npmjs.com/package/spdy). This option is ignored for Node 15.0.0 and above, as spdy is broken for those versions. The dev server will migrate over to Node's built-in HTTP/2 once [Express](https://expressjs.com/) supports it.
615-
616-
HTTP/2 with a self-signed certificate:
617-
618-
**webpack.config.js**
619-
620-
```javascript
621-
module.exports = {
622-
//...
623-
devServer: {
624-
http2: true,
625-
},
626-
};
627-
```
628-
629-
Usage via CLI
630-
631-
```bash
632-
npx webpack serve --http2
633-
```
634-
635-
To disable:
636-
637-
```bash
638-
npx webpack serve --no-http2
639-
```
640-
641-
Provide your own certificate using the [https](#devserverhttps) option:
642-
643-
**webpack.config.js**
644-
645-
```javascript
646-
const fs = require('fs');
647-
648-
module.exports = {
649-
//...
650-
devServer: {
651-
http2: true,
652-
https: {
653-
key: fs.readFileSync('/path/to/server.key'),
654-
cert: fs.readFileSync('/path/to/server.crt'),
655-
ca: fs.readFileSync('/path/to/ca.pem'),
656-
},
657-
},
658-
};
659-
```
660-
661-
To pass your certificate via CLI, use the following options:
662-
663-
```bash
664-
npx webpack serve --http2 --https-key ./path/to/server.key --https-cert ./path/to/server.crt --https-ca ./path/to/ca.pem
665-
```
666-
667-
W> This option is deprecated in favor of the [devServer.server](#devserverserver) option.
668-
669-
## devServer.https
670-
671-
`boolean` `object`
672-
673-
By default, dev-server will be served over `HTTP`. It can optionally be served over `HTTPS`:
674-
675-
**webpack.config.js**
676-
677-
```javascript
678-
module.exports = {
679-
//...
680-
devServer: {
681-
https: true,
682-
},
683-
};
684-
```
685-
686-
Usage via the CLI:
687-
688-
```bash
689-
npx webpack serve --https
690-
```
691-
692-
To disable:
693-
694-
```bash
695-
npx webpack serve --no-https
696-
```
697-
698-
With the above setting, a self-signed certificate is used, but you can provide your own:
699-
700-
**webpack.config.js**
701-
702-
```javascript
703-
module.exports = {
704-
devServer: {
705-
https: {
706-
ca: './path/to/server.pem',
707-
pfx: './path/to/server.pfx',
708-
key: './path/to/server.key',
709-
cert: './path/to/server.crt',
710-
passphrase: 'webpack-dev-server',
711-
requestCert: true,
712-
},
713-
},
714-
};
715-
```
716-
717-
This object is passed straight to the Node.js HTTPS module, so see the [HTTPS documentation](https://nodejs.org/api/https.html) for more information.
718-
719-
To pass your own certificate via the CLI use the following options:
720-
721-
```bash
722-
npx webpack serve --https-request-cert --https-key ./path/to/server.key --https-cert ./path/to/server.crt --https-ca ./path/to/ca.pem --https-pfx ./path/to/server.pfx --https-passphrase webpack-dev-server
723-
```
724-
725-
`webpack-dev-server >= v4.2.0` allows you to set additional [TLS options](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) like `minVersion`. Also, you can directly pass the contents of respective files:
726-
727-
**webpack.config.js**
728-
729-
```javascript
730-
const fs = require('fs');
731-
const path = require('path');
732-
733-
module.exports = {
734-
devServer: {
735-
https: {
736-
minVersion: 'TLSv1.1',
737-
key: fs.readFileSync(path.join(__dirname, './server.key')),
738-
pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
739-
cert: fs.readFileSync(path.join(__dirname, './server.crt')),
740-
ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
741-
passphrase: 'webpack-dev-server',
742-
requestCert: true,
743-
},
744-
},
745-
};
746-
```
747-
748-
W> Don't specify `https.ca` and `https.cacert` options together, if specified `https.ca` will be used. `https.cacert` is deprecated and will be removed in the next major release.
749-
750-
W> This option is deprecated in favor of the [devServer.server](#devserverserver) option.
751-
752610
## devServer.headers
753611

754612
`array` `function` `object`
@@ -1042,94 +900,6 @@ npx webpack serve --no-live-reload
1042900

1043901
W> Live reloading works only with web related [targets](/configuration/target/#string) like `web`, `webworker`, `electron-renderer` and `node-webkit`.
1044902

1045-
## devServer.magicHtml
1046-
1047-
`boolean = true`
1048-
1049-
<Badge text="v4.1.0+" />
1050-
1051-
Tell dev-server to enable/disable magic HTML routes (routes corresponding to your webpack output, for example `/main` for `main.js`).
1052-
1053-
**webpack.config.js**
1054-
1055-
```javascript
1056-
module.exports = {
1057-
//...
1058-
devServer: {
1059-
magicHtml: true,
1060-
},
1061-
};
1062-
```
1063-
1064-
Usage via the CLI:
1065-
1066-
```bash
1067-
npx webpack serve --magic-html
1068-
```
1069-
1070-
To disable:
1071-
1072-
```bash
1073-
npx webpack serve --no-magic-html
1074-
```
1075-
1076-
## devServer.onAfterSetupMiddleware
1077-
1078-
`function (devServer)`
1079-
1080-
Provides the ability to execute custom middleware after all other middleware
1081-
internally within the server.
1082-
1083-
**webpack.config.js**
1084-
1085-
```javascript
1086-
module.exports = {
1087-
//...
1088-
devServer: {
1089-
onAfterSetupMiddleware: function (devServer) {
1090-
if (!devServer) {
1091-
throw new Error('webpack-dev-server is not defined');
1092-
}
1093-
1094-
devServer.app.get('/some/path', function (req, res) {
1095-
res.json({ custom: 'response' });
1096-
});
1097-
},
1098-
},
1099-
};
1100-
```
1101-
1102-
W> This option is deprecated in favor of the [devServer.setupMiddlewares](#devserversetupmiddlewares) option.
1103-
1104-
## devServer.onBeforeSetupMiddleware
1105-
1106-
`function (devServer)`
1107-
1108-
Provides the ability to execute custom middleware prior to all other middleware
1109-
internally within the server. This could be used to define custom handlers, for
1110-
example:
1111-
1112-
**webpack.config.js**
1113-
1114-
```javascript
1115-
module.exports = {
1116-
//...
1117-
devServer: {
1118-
onBeforeSetupMiddleware: function (devServer) {
1119-
if (!devServer) {
1120-
throw new Error('webpack-dev-server is not defined');
1121-
}
1122-
1123-
devServer.app.get('/some/path', function (req, res) {
1124-
res.json({ custom: 'response' });
1125-
});
1126-
},
1127-
},
1128-
};
1129-
```
1130-
1131-
W> This option is deprecated in favor of the [devServer.setupMiddlewares](#devserversetupmiddlewares) option.
1132-
1133903
## devserver.onListening
1134904

1135905
`function (devServer)`
@@ -1309,7 +1079,7 @@ npx webpack serve --port auto
13091079

13101080
## devServer.proxy
13111081

1312-
`object` `[object, function]`
1082+
`[object, function]`
13131083

13141084
Proxying some URLs can be useful when you have a separate API backend development server and you want to send API requests on the same domain.
13151085

@@ -1323,9 +1093,12 @@ With a backend on `localhost:3000`, you can use this to enable proxying:
13231093
module.exports = {
13241094
//...
13251095
devServer: {
1326-
proxy: {
1327-
'/api': 'http://localhost:3000',
1328-
},
1096+
proxy: [
1097+
{
1098+
context: ['/api'],
1099+
target: 'http://localhost:3000',
1100+
},
1101+
],
13291102
},
13301103
};
13311104
```
@@ -1340,12 +1113,13 @@ If you don't want `/api` to be passed along, we need to rewrite the path:
13401113
module.exports = {
13411114
//...
13421115
devServer: {
1343-
proxy: {
1344-
'/api': {
1116+
proxy: [
1117+
{
1118+
context: ['/api'],
13451119
target: 'http://localhost:3000',
13461120
pathRewrite: { '^/api': '' },
13471121
},
1348-
},
1122+
],
13491123
},
13501124
};
13511125
```
@@ -1358,12 +1132,13 @@ A backend server running on HTTPS with an invalid certificate will not be accept
13581132
module.exports = {
13591133
//...
13601134
devServer: {
1361-
proxy: {
1362-
'/api': {
1363-
target: 'https://other-server.example.com',
1135+
proxy: [
1136+
{
1137+
context: ['/api'],
1138+
target: 'http://localhost:3000',
13641139
secure: false,
13651140
},
1366-
},
1141+
],
13671142
},
13681143
};
13691144
```
@@ -1384,8 +1159,9 @@ E.g. for a browser request, you want to serve an HTML page, but for an API reque
13841159
module.exports = {
13851160
//...
13861161
devServer: {
1387-
proxy: {
1388-
'/api': {
1162+
proxy: [
1163+
{
1164+
context: ['/api'],
13891165
target: 'http://localhost:3000',
13901166
bypass: function (req, res, proxyOptions) {
13911167
if (req.headers.accept.indexOf('html') !== -1) {
@@ -1394,11 +1170,13 @@ module.exports = {
13941170
}
13951171
},
13961172
},
1397-
},
1173+
],
13981174
},
13991175
};
14001176
```
14011177

1178+
W> The `bypass` option is deprecated for proxy in favor of the `router` and the `context` options. [Read more here](https://github.com/chimurai/http-proxy-middleware/tree/v2.0.6#http-proxy-middleware-options).
1179+
14021180
If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a `context` property:
14031181

14041182
**webpack.config.js**
@@ -1428,10 +1206,12 @@ module.exports = {
14281206
devMiddleware: {
14291207
index: false, // specify to enable root proxying
14301208
},
1431-
proxy: {
1432-
context: () => true,
1433-
target: 'http://localhost:1234',
1434-
},
1209+
proxy: [
1210+
{
1211+
context: () => true,
1212+
target: 'http://localhost:1234',
1213+
},
1214+
],
14351215
},
14361216
};
14371217
```
@@ -1444,12 +1224,13 @@ The origin of the host header is kept when proxying by default, you can set `cha
14441224
module.exports = {
14451225
//...
14461226
devServer: {
1447-
proxy: {
1448-
'/api': {
1227+
proxy: [
1228+
{
1229+
context: ['/api'],
14491230
target: 'http://localhost:3000',
14501231
changeOrigin: true,
14511232
},
1452-
},
1233+
],
14531234
},
14541235
};
14551236
```
@@ -1575,8 +1356,6 @@ module.exports = {
15751356
};
15761357
```
15771358

1578-
W> Don't specify `server.options.ca` and `server.options.cacert` options together, if specified `server.options.ca` will be used. `server.options.cacert` is deprecated and will be removed in the next major release.
1579-
15801359
## devServer.setupExitSignals
15811360

15821361
`boolean = true`

0 commit comments

Comments
 (0)