diff --git a/src/content/configuration/dev-server.mdx b/src/content/configuration/dev-server.mdx index 44f6460523c1..7bde56012d5f 100644 --- a/src/content/configuration/dev-server.mdx +++ b/src/content/configuration/dev-server.mdx @@ -26,13 +26,11 @@ contributors: This page describes the options that affect the behavior of webpack-dev-server (short: dev-server). -T> Options that are compatible with [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) have 🔑 next to them. - ## `devServer` `object` -This set of options is picked up by [webpack-dev-server](https://github.com/webpack/webpack-dev-server) and can be used to change its behavior in various ways. Here's a rudimentary example that gzips and serves everything from our `dist/` directory in the project root: +This set of options is picked up by [webpack-dev-server](https://github.com/webpack/webpack-dev-server) and can be used to change its behavior in various ways. Here's a rudimentary example that gzips and serves everything from our `public/` directory in the project root: **webpack.config.js** @@ -42,7 +40,9 @@ var path = require('path'); module.exports = { //... devServer: { - contentBase: path.join(__dirname, 'dist'), + static: { + directory: path.join(__dirname, 'public'), + }, compress: true, port: 9000, }, @@ -52,14 +52,16 @@ module.exports = { When the server is started, there will be a message prior to the list of resolved modules: ```bash -http://localhost:9000/ -webpack output is served from /build/ -Content not from webpack is served from /path/to/dist/ + [webpack-dev-server] Project is running at: + [webpack-dev-server] Loopback: http://localhost:9000/ + [webpack-dev-server] On Your Network (IPv4): http://197.158.164.104:9000/ + [webpack-dev-server] On Your Network (IPv6): http://[fe80::1]:9000/ + [webpack-dev-server] Content not from webpack is served from '/path/to/public' directory ``` that will give some background on where the server is located and what it's serving. -If you're using dev-server through the Node.js API, the options in `devServer` will be ignored. Pass the options as a second parameter instead: `new WebpackDevServer(compiler, {...})`. [See here](https://github.com/webpack/webpack-dev-server/tree/master/examples/api/simple) for an example of how to use webpack-dev-server through the Node.js API. +If you're using dev-server through the Node.js API, the options in `devServer` will be ignored. Pass the options as the first parameter instead: `new WebpackDevServer({...}, compiler)`. [See here](https://github.com/webpack/webpack-dev-server/tree/master/examples/api/simple) for an example of how to use webpack-dev-server through the Node.js API. W> You cannot use the second `compiler` argument (a callback) when using `WebpackDevServer`. @@ -81,29 +83,9 @@ npx webpack serve A list of CLI options for `serve` is available [here](https://github.com/webpack/webpack-cli/blob/master/SERVE-OPTIONS-v3.md) -## `devServer.after` - -`function (app, server, compiler)` - -Provides the ability to execute custom middleware after all other middleware -internally within the server. - -**webpack.config.js** - -```javascript -module.exports = { - //... - devServer: { - after: function (app, server, compiler) { - // do fancy stuff - }, - }, -}; -``` - ## `devServer.allowedHosts` -`[string]` +`'auto' | 'all'` `[string]` This option allows you to whitelist services that are allowed to access the dev server. @@ -139,19 +121,7 @@ module.exports = { }; ``` -To use this option with the CLI pass the `--allowed-hosts` as following: - -```bash -npx webpack serve --entry ./entry/file --output-path ./output/path --allowed-hosts .host.com --allowed-hosts host2.com -``` - -## `devServer.before` - -`function (app, server, compiler)` - -Provides the ability to execute custom middleware prior to all other middleware -internally within the server. This could be used to define custom handlers, for -example: +When set to `'all'` this option bypasses host checking. **THIS IS NOT RECOMMENDED** as apps that do not check the host are vulnerable to DNS rebinding attacks. **webpack.config.js** @@ -159,20 +129,22 @@ example: module.exports = { //... devServer: { - before: function (app, server, compiler) { - app.get('/some/path', function (req, res) { - res.json({ custom: 'response' }); - }); - }, + allowedHosts: 'all', }, }; ``` +To use this option with the CLI pass the `--allowed-hosts` as following: + +```bash +npx webpack serve --entry ./entry/file --output-path ./output/path --allowed-hosts .host.com --allowed-hosts host2.com +``` + ## `devServer.bonjour` -`boolean = false` +`boolean` `object` -This option broadcasts the server via [ZeroConf](http://www.zeroconf.org/) networking on start +This option broadcasts the server via [ZeroConf](http://www.zeroconf.org/) networking on start. **webpack.config.js** @@ -185,21 +157,13 @@ module.exports = { }; ``` -Usage via the CLI +Usage via the CLI: ```bash npx webpack serve --bonjour ``` -## `devServer.clientLogLevel` - -`string = 'info': 'silent' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'none' | 'warning'` - -W> `silent`, `trace`, `debug`, and `warning` are going to be deprecated at the next major version. - -When using _inline mode_, the console in your DevTools will show you messages e.g. before reloading, before an error or when [Hot Module Replacement](/concepts/hot-module-replacement/) is enabled. - -`devServer.clientLogLevel` may be too verbose, you can turn logging off by setting it to `'silent'`. +You can also pass [custom options](https://github.com/watson/bonjour#initializing) to bonjour, for example: **webpack.config.js** @@ -207,22 +171,21 @@ When using _inline mode_, the console in your DevTools will show you messages e. module.exports = { //... devServer: { - clientLogLevel: 'silent', + bonjour: { + type: 'http', + protocol: 'udp', + }, }, }; ``` -Usage via the CLI - -```bash -npx webpack serve --client-log-level silent -``` +## `devServer.client` -## `devServer.compress` +### `logging` -`boolean` +`'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'` -Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/) for everything served: +Allows to set log level in the browser, e.g. before reloading, before an error or when [Hot Module Replacement](/concepts/hot-module-replacement/) is enabled. **webpack.config.js** @@ -230,103 +193,71 @@ Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-y module.exports = { //... devServer: { - compress: true, + client: { + logging: 'info', + }, }, }; ``` -Usage via the CLI +Usage via the CLI: ```bash -npx webpack serve --compress +npx webpack serve --client-logging info ``` -## `devServer.contentBase` +### `overlay` -`boolean: false` `string` `[string]` `number` +`boolean = true` `object: { errors boolean = true, warnings boolean = true }` -Tell the server where to serve content from. This is only necessary if you want to serve static files. [`devServer.publicPath`](#devserverpublicpath-) will be used to determine where the bundles should be served from, and takes precedence. - -T> It is recommended to use an absolute path. - -By default, it will use your current working directory to serve content. To disable `contentBase` set it to `false`. +Shows a full-screen overlay in the browser when there are compiler errors or warnings. **webpack.config.js** ```javascript -const path = require('path'); - module.exports = { //... devServer: { - contentBase: path.join(__dirname, 'public'), - }, -}; -``` - -It is also possible to serve from multiple directories in case you want to serve static content at multiple URLs with [`contentBasePublicPath`](#devservercontentbasepublicpath): - -**webpack.config.js** - -```javascript -const path = require('path'); - -module.exports = { - //... - devServer: { - contentBase: [ - path.join(__dirname, 'public'), - path.join(__dirname, 'assets'), - ], + client: { + overlay: true, + }, }, }; ``` -Usage via the CLI +Usage via the CLI: ```bash -npx webpack serve --content-base ./path/to/content/dir +npx webpack serve --client-overlay ``` -## `devServer.contentBasePublicPath` - -`string = '/'` `[string]` - -Tell the server at what URL to serve `devServer.contentBase` static content. If there was a file `assets/manifest.json`, it would be served at `/serve-content-base-at-this-url/manifest.json` +If you want to show only errors: **webpack.config.js** ```javascript -const path = require('path'); - module.exports = { //... devServer: { - contentBase: path.join(__dirname, 'assets'), - contentBasePublicPath: '/serve-content-base-at-this-url', + client: { + overlay: { + errors: true, + warnings: false, + }, + }, }, }; ``` -Provide an array of strings in case you have multiple static folders set in [`contentBase`](#devservercontentbase). - -**webpack.config.js** +Usage via the CLI: -```javascript -module.exports = { - //... - devServer: { - contentBase: [contentBasePublic, contentBaseOther], - contentBasePublicPath: [contentBasePublicPath, contentBasePublicOtherPath], - }, -}; +```bash +npx webpack serve --client-overlay-errors --no-client-overlay-warnings ``` -## `devServer.disableHostCheck` - -`boolean` +### `progress` -When set to `true` this option bypasses host checking. **THIS IS NOT RECOMMENDED** as apps that do not check the host are vulnerable to DNS rebinding attacks. +Prints compilation progress in percentage in the browser. **webpack.config.js** @@ -334,50 +265,52 @@ When set to `true` this option bypasses host checking. **THIS IS NOT RECOMMENDED module.exports = { //... devServer: { - disableHostCheck: true, + client: { + progress: true, + }, }, }; ``` -Usage via the CLI +Usage via the CLI: ```bash -npx webpack serve --disable-host-check +npx webpack serve --client-progress ``` -## `devServer.filename` 🔑 +### webSocketTransport -`string` +`'ws' | 'sockjs'` `string` -This option lets you reduce the compilations in [lazy mode](#devserverlazy-). -By default in [lazy mode](#devserverlazy-), every request results in a new compilation. With `filename`, it's possible to only compile when a certain file is requested. +This option allows us either to choose the current `devServer` transport mode for client individually or to provide custom client implementation. This allows to specify how browser or other client communicates with the `devServer`. -If [`output.filename`](/configuration/output/#outputfilename) is set to `'bundle.js'` and `devServer.filename` is used like this: +T> Providing `'ws'` or `'sockjs'` to [`webSocketServer`](#devserverwebsocketserver) is a shortcut to setting both `devServer.client.webSocketTransport` and `devServer.webSocketServer` to the given value. **webpack.config.js** ```javascript module.exports = { //... - output: { - filename: 'bundle.js', - }, devServer: { - lazy: true, - filename: 'bundle.js', + client: { + webSocketTransport: 'ws', + }, + webSocketServer: 'ws', }, }; ``` -It will now only compile the bundle when `/bundle.js` is requested. +Usage via the CLI: -T> `filename` has no effect when used without [lazy mode](#devserverlazy-). +```bash +npx webpack serve --client-web-socket-transport ws --web-socket-server ws +``` -## `devServer.headers` 🔑 +T> When providing a custom client and server implementation make sure that they are compatible with one another to communicate successfully. -`object` +To create a custom client implementation, create a class that extends [`BaseClient`](https://github.com/webpack/webpack-dev-server/blob/master/client-src/clients/BaseClient.js). -Adds headers to all responses: +Using path to `CustomClient.js`, a custom WebSocket client implementation, along with the compatible `'ws'` server: **webpack.config.js** @@ -385,18 +318,15 @@ Adds headers to all responses: module.exports = { //... devServer: { - headers: { - 'X-Custom-Foo': 'bar', + client: { + webSocketTransport: require.resolve('./CustomClient'), }, + webSocketServer: 'ws', }, }; ``` -## `devServer.historyApiFallback` - -`boolean = false` `object` - -When using the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History), the `index.html` page will likely have to be served in place of any `404` responses. Enable `devServer.historyApiFallback` by setting it to `true`: +Using custom, compatible WebSocket client and server implementations: **webpack.config.js** @@ -404,31 +334,19 @@ When using the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/ module.exports = { //... devServer: { - historyApiFallback: true, + client: { + webSocketTransport: require.resolve('./CustomClient'), + }, + webSocketServer: require.resolve('./CustomServer'), }, }; ``` -By passing an object this behavior can be controlled further using options like `rewrites`: +### webSocketURL -**webpack.config.js** +`string` `object` -```javascript -module.exports = { - //... - devServer: { - historyApiFallback: { - rewrites: [ - { from: /^\/$/, to: '/views/landing.html' }, - { from: /^\/subpage/, to: '/views/subpage.html' }, - { from: /./, to: '/views/404.html' }, - ], - }, - }, -}; -``` - -When using dots in your path (common with Angular), you may need to use the `disableDotRule`: +This option allows to specify URL to web socket server (useful when you're proxying dev server and client script does not always know where to connect to). **webpack.config.js** @@ -436,26 +354,27 @@ When using dots in your path (common with Angular), you may need to use the `dis module.exports = { //... devServer: { - historyApiFallback: { - disableDotRule: true, + client: { + webSocketURL: 'ws://0.0.0.0:8080/ws', }, }, }; ``` -Usage via the CLI +Usage via the CLI: ```bash -npx webpack serve --history-api-fallback +npx webpack serve --client-web-socket-url ws://0.0.0.0:8080/ws ``` -For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation. - -## `devServer.host` - -`string = 'localhost'` +You can also specify an object with the following properties: -Specify a host to use. If you want your server to be accessible externally, specify it like this: +- `hostname`: Tells clients connected to devServer to use the provided hostname. +- `pathname`: Tells clients connected to devServer to use the provided path to connect. +- `password`: Tells clients connected to devServer to use the provided password to authenticate. +- `port`: Tells clients connected to devServer to use the provided port. +- `protocol`: Tells clients connected to devServer to use the provided protocol. +- `username`: Tells clients connected to devServer to use the provided username to authenticate. **webpack.config.js** @@ -463,22 +382,27 @@ Specify a host to use. If you want your server to be accessible externally, spec module.exports = { //... devServer: { - host: '0.0.0.0', + client: { + webSocketURL: { + hostname: '0.0.0.0', + pathname: '/ws', + password: 'dev-server', + port: 8080, + protocol: 'ws', + username: 'webpack', + }, + }, }, }; ``` -Usage via the CLI - -```bash -npx webpack serve --host 0.0.0.0 -``` +T> To get `protocol`/`hostname`/`port` from browser use `webSocketURL: 'auto://0.0.0.0:0/ws'`. -## `devServer.hot` +## `devServer.compress` -`boolean` +`boolean = true` -Enable webpack's [Hot Module Replacement](/concepts/hot-module-replacement/) feature: +Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/) for everything served: **webpack.config.js** @@ -486,43 +410,40 @@ Enable webpack's [Hot Module Replacement](/concepts/hot-module-replacement/) fea module.exports = { //... devServer: { - hot: true, + compress: true, }, }; ``` -T> Note that [`webpack.HotModuleReplacementPlugin`](/plugins/hot-module-replacement-plugin/) is required to fully enable HMR. If `webpack` or `webpack-dev-server` are launched with the `--hot` option, this plugin will be added automatically, so you may not need to add this to your `webpack.config.js`. See the [HMR concepts page](/concepts/hot-module-replacement/) for more information. +Usage via the CLI: -## `devServer.hotOnly` +```bash +npx webpack serve --compress +``` -`boolean` +## devserver.devMiddleware -Enables Hot Module Replacement (see [`devServer.hot`](#devserverhot)) without page refresh as a fallback in case of build failures. +Provide options to [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) which handles webpack assets. **webpack.config.js** ```javascript module.exports = { - //... devServer: { - hotOnly: true, + index: true, + mimeTypes: { 'text/html': ['phtml'] }, + publicPath: '/publicPathForDevServe', + serverSideRender: true, + writeToDisk: true, }, }; ``` -Usage via the CLI - -```bash -npx webpack serve --hot-only -``` - ## `devServer.http2` -`boolean = false` - -Serve over HTTP/2 using [spdy](https://www.npmjs.com/package/spdy). This option is ignored for Node 10.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. +`boolean` -If `devServer.http2` is not explicitly set to `false`, it will default to `true` when [`devServer.https`](#devserverhttps) is enabled. When `devServer.http2` is enabled but the server is unable to serve over HTTP/2, the server defaults to HTTPS. +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. HTTP/2 with a self-signed certificate: @@ -549,7 +470,7 @@ module.exports = { https: { key: fs.readFileSync('/path/to/server.key'), cert: fs.readFileSync('/path/to/server.crt'), - ca: fs.readFileSync('/path/to/ca.pem'), + cacert: fs.readFileSync('/path/to/ca.pem'), }, }, }; @@ -564,14 +485,14 @@ npx webpack serve --http2 To pass your own certificate via CLI, use the following options ```bash -npx webpack serve --http2 --key ./path/to/server.key --cert ./path/to/server.crt --cacert ./path/to/ca.pem +npx webpack serve --http2 --https-key ./path/to/server.key --https-cert ./path/to/server.crt --https-cacert ./path/to/ca.pem ``` ## `devServer.https` `boolean` `object` -By default, dev-server will be served over HTTP. It can optionally be served over HTTP/2 with HTTPS: +By default, dev-server will be served over `HTTP`. It can optionally be served over `HTTP/2` with `HTTPS`: **webpack.config.js** @@ -590,12 +511,14 @@ With the above setting, a self-signed certificate is used, but you can provide y ```javascript module.exports = { - //... devServer: { https: { - key: fs.readFileSync('/path/to/server.key'), - cert: fs.readFileSync('/path/to/server.crt'), - ca: fs.readFileSync('/path/to/ca.pem'), + cacert: './server.pem', + pfx: './server.pfx', + key: './server.key', + cert: './server.crt', + passphrase: 'webpack-dev-server', + requestCert: true, }, }, }; @@ -603,7 +526,7 @@ module.exports = { This object is passed straight to Node.js HTTPS module, so see the [HTTPS documentation](https://nodejs.org/api/https.html) for more information. -Usage via the CLI +Usage via the CLI: ```bash npx webpack serve --https @@ -612,14 +535,14 @@ npx webpack serve --https To pass your own certificate via the CLI use the following options ```bash -npx webpack serve --https --key ./path/to/server.key --cert ./path/to/server.crt --cacert ./path/to/ca.pem +npx webpack serve --https-key ./path/to/server.key --https--cert ./path/to/server.crt --https-cacert ./path/to/ca.pem ``` -## `devServer.index` +## `devServer.headers` -`string` +`function` `object` -The filename that is considered the index file. +Adds headers to all responses: **webpack.config.js** @@ -627,51 +550,50 @@ The filename that is considered the index file. module.exports = { //... devServer: { - index: 'index.html', + headers: { + 'X-Custom-Foo': 'bar', + }, }, }; ``` -## `devServer.injectClient` +## devServer.historyApiFallback -`boolean = false` `function (compilerConfig) => boolean` +`boolean` `object` -Tells `devServer` to inject a client. Setting `devServer.injectClient` to `true` will result in always injecting a client. It is possible to provide a function to inject conditionally: +When using the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History), the `index.html` page will likely have to be served in place of any `404` responses. Enable `devServer.historyApiFallback` by setting it to `true`: + +**webpack.config.js** ```javascript module.exports = { //... devServer: { - injectClient: (compilerConfig) => compilerConfig.name === 'only-include', + historyApiFallback: true, }, }; ``` -## `devServer.injectHot` - -`boolean = false` `function (compilerConfig) => boolean` +By passing an object this behavior can be controlled further using options like `rewrites`: -Tells `devServer` to inject a Hot Module Replacement. Setting `devServer.injectHot` to `true` will result in always injecting. It is possible to provide a function to inject conditionally: +**webpack.config.js** ```javascript module.exports = { //... devServer: { - hot: true, - injectHot: (compilerConfig) => compilerConfig.name === 'only-include', + historyApiFallback: { + rewrites: [ + { from: /^\/$/, to: '/views/landing.html' }, + { from: /^\/subpage/, to: '/views/subpage.html' }, + { from: /./, to: '/views/404.html' }, + ], + }, }, }; ``` -W> Make sure that [`devServer.hot`](#devserverhot) is set to `true` because `devServer.injectHot` only works with HMR. - -## `devServer.inline` - -`boolean` - -Toggle between the dev-server's two different modes. By default, the application will be served with _inline mode_ enabled. This means that a script will be inserted in your bundle to take care of live reloading, and build messages will appear in the browser console. - -It is also possible to use **iframe mode**, which uses an `