Skip to content

Add documentation for devServer cli options #1468

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 28 commits into from
Aug 1, 2017
Merged
Changes from 26 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
c3fcef3
dev server config - allowed-hosts - CLI
orteth01 Jul 31, 2017
ba84405
dev server config - bonjour
orteth01 Jul 31, 2017
2b23611
dev server config - lazy - CLI
orteth01 Jul 31, 2017
f48fb6a
dev server config - inline - CLI
orteth01 Jul 31, 2017
15a453d
dev server config - progress - CLI
orteth01 Jul 31, 2017
3982cf2
dev server config - hot-only - CLI
orteth01 Jul 31, 2017
26ff89d
dev server config - stdin - CLI
orteth01 Jul 31, 2017
dd2270e
dev server config - open
orteth01 Jul 31, 2017
4eac478
dev server config - useLocalIp
orteth01 Jul 31, 2017
d70418e
dev server config - openPage
orteth01 Jul 31, 2017
b575b2f
dev server config - color - CLI
orteth01 Jul 31, 2017
3e59e96
dev server config - info - CLI
orteth01 Jul 31, 2017
4282e3c
dev server config - quiet - CLI
orteth01 Jul 31, 2017
5b1db69
dev server config - client-log-level - CLI
orteth01 Jul 31, 2017
c91a733
dev server config - https - CLI
orteth01 Jul 31, 2017
53c5265
dev server config - pfx
orteth01 Jul 31, 2017
96cc810
dev server config - pfxPassphrase
orteth01 Jul 31, 2017
60ceef2
dev server config - content-base - CLI
orteth01 Jul 31, 2017
7708519
dev server config - watch-content-base - CLI
orteth01 Jul 31, 2017
c1cade6
dev server config - history-api-fallback - CLI
orteth01 Jul 31, 2017
5ebea74
dev server config - compress - CLI
orteth01 Jul 31, 2017
ebf7031
dev server config - port - CLI
orteth01 Jul 31, 2017
e31e39b
dev server config - disableHostCheck
orteth01 Jul 31, 2017
216bfa3
dev server config - socket
orteth01 Jul 31, 2017
e7071aa
dev server config - public - CLI
orteth01 Jul 31, 2017
73721b5
dev server config - host - CLI
orteth01 Jul 31, 2017
24e4d56
fix formatting errors
orteth01 Jul 31, 2017
81f7695
docs(config): remove a "CLI only" flag in dev-server
skipjack Aug 1, 2017
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 220 additions & 4 deletions content/configuration/dev-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,24 @@ allowedHosts: [
]
```

To use this option with the CLI pass the `--allowed-hosts` option a comma-delimited string.

```
webpack-dev-server --entry /entry/file --output-path /output/path --allowed-hosts .host.com,host2.com
```

## `devServer.bonjour`

This option broadcasts the server via ZeroConf networking on start

```js
bonjour: true
```

Usage via the CLI
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to add a line break between each fenced code block and the paragraph above it.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is why the build is currently failing.

webpack-dev-server --bonjour
```

## `devServer.clientLogLevel`

Expand All @@ -87,10 +105,24 @@ You can prevent all these messages from showing, by using this option:
clientLogLevel: "none"
```

Usage via the CLI
```
webpack-dev-server --client-log-level none
```

Possible values are `none`, `error`, `warning` or `info` (default).

Note that the console will *always* show bundle errors and warnings. This option only effects the message before it.

## `devServer.color` - CLI only

`boolean`

Enables/Disables colors on the console.
```
webpack-dev-server --color
```


## `devServer.compress`

Expand All @@ -102,6 +134,10 @@ Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-y
compress: true
```

Usage via the CLI
```
webpack-dev-server --compress
```

## `devServer.contentBase`

Expand Down Expand Up @@ -129,6 +165,25 @@ To disable `contentBase`:
contentBase: false
```

Usage via the CLI
```
webpack-dev-server --content-base /path/to/content/dir
```

## `devServer.disableHostCheck`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was this option intentionally left out of the docs to prevent people from using it? If so, I can remove this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was this option intentionally left out of the docs to prevent people from using it? If so, I can remove this.

commented on an earlier, now-out-of-date commit. just want to make sure this is alright

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think if it's an available option and it's noted by the CLI when running webpack-dev-server -h then it should be documented here as well. Your "THIS IS NOT RECOMMENDED..." is prominent enough that people should notice this, and if they choose to proceed anyway, so be it.

I'm going to do one last skim and then merge this. @SpaceK33z if you have a chance to review this later on and come across any issues -- please ping us so we can resolve in a separate PR.


`boolean`

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.

```js
disableHostCheck: true
```

Usage via the CLI
```
webpack-dev-server --disable-host-check
```

## `devServer.filename` 🔑

Expand Down Expand Up @@ -192,10 +247,15 @@ historyApiFallback: {
}
```

Usage via the CLI
```
webpack-dev-server --history-api-fallback
```

For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation.


## `devServer.host` - CLI only
## `devServer.host`

`string`

Expand All @@ -205,6 +265,11 @@ Specify a host to use. By default this is `localhost`. If you want your server t
host: "0.0.0.0"
```

Usage via the CLI
```
webpack-dev-server --host 0.0.0.0
```


## `devServer.hot`

Expand All @@ -219,7 +284,7 @@ hot: true
T> Note that you must also include a `new webpack.HotModuleReplacementPlugin()` to fully enable HMR. See the [HMR concepts page](/concepts/hot-module-replacement) for more information.


## `devServer.hotOnly` - CLI only
## `devServer.hotOnly`

`boolean`

Expand All @@ -229,6 +294,10 @@ Enables Hot Module Replacement (see [`devServer.hot`](#devserver-hot)) without p
hotOnly: true
```

Usage via the CLI
```
webpack-dev-server --hot-only
```

## `devServer.https`

Expand All @@ -252,6 +321,24 @@ https: {

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
```
webpack-dev-server --https
```

To pass your own certificate via the CLI use the following options
```
webpack-dev-server --https --key /path/to/server.key --cert /path/to/server.crt --cacert /path/to/ca.pem
```

## `devServer.info` - CLI only

`boolean`

Output cli information. It is enabled by default.
```
webpack-dev-server --info=false
```

## `devServer.inline` - CLI only
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should drop the "CLI only" flag here as well unless it was removed in a recent version. I've definitely used inline via the configuration before.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@orteth01 I'm just going to make this change so we can get this merged. Ping me if I'm wrong on this though and we can fix in a separate PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@skipjack yea you're totally right. I must have just missed this one. my bad!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No worries, thanks again for this update! If you don't mind I may ping you in the future if there's other questions re this page since it seems like you have some familiarity with the webpack-dev-server repo.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you don't mind I may ping you in the future if there's other questions re this page

yea no problem! happy to help!


Expand All @@ -265,6 +352,11 @@ It is also possible to use **iframe mode**, which uses an `<iframe>` under a not
inline: false
```

Usage via the CLI
```
webpack-dev-server --inline=false
```

T> Inline mode is recommended when using Hot Module Replacement.


Expand All @@ -278,6 +370,11 @@ When `lazy` is enabled, the dev-server will only compile the bundle when it gets
lazy: true
```

Usage via the CLI
```
webpack-dev-server --lazy
```

T> `watchOptions` will have no effect when used with **lazy mode**.

T> If you use the CLI, make sure **inline mode** is disabled.
Expand All @@ -293,6 +390,36 @@ With `noInfo` enabled, messages like the webpack bundle information that is show
noInfo: true
```

## `devServer.open`

`boolean`

When `open` is enabled, the dev server will open the browser.

```js
open: true
```

Usage via the CLI
```
webpack-dev-server --open
```

## `devServer.openPage`

`string`

Specify a page to navigate to when opening the browser.

```js
openPage: '/different/page'
```

Usage via the CLI
```
webpack-dev-server --open-page "/different/page"
```

## `devServer.overlay`

`boolean` `object`
Expand All @@ -312,7 +439,36 @@ overlay: {
}
```

## `devServer.port` - CLI only
## `devServer.pfx`

`string`

Path to a SSL pfx file.

```js
pfx: '/path/to/file.pfx'
```

Usage via the CLI
```
webpack-dev-server --pfx /path/to/file.pfx
```

## `devServer.pfxPassphrase`

`string`

The passphrase to a SSL PFX file.
```js
pfxPassphrase: 'passphrase'
```

Usage via the CLI
```
webpack-dev-server --pfx-passphrase passphrase
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be two line breaks between each section -- it seems on some you did add two but at least a few of these only have one.

## `devServer.port`

`number`

Expand All @@ -322,6 +478,10 @@ Specify a port number to listen for requests on:
port: 8080
```

Usage via the CLI
```
webpack-dev-server --port 8080
```

## `devServer.proxy`

Expand Down Expand Up @@ -389,9 +549,12 @@ proxy: {
`boolean`

Output running progress to console.
```
webpack-dev-server --progress
```


## `devServer.public` - CLI only
## `devServer.public`

`string`

Expand All @@ -403,6 +566,11 @@ For example, the dev-server is proxied by nginx, and available on `myapp.test`:
public: "myapp.test:80"
```

Usage via the CLI
```
webpack-dev-server --public myapp.test:80
```


## `devServer.publicPath` 🔑
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@simon04 (or @orteth01) do either of you know the purpose of the key icons? Can we drop them?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or @SpaceK33z? I'm not sure what they're supposed to indicate. If they were meaningful maybe we can think of a more intuitive display.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Options that are compatible with webpack-dev-middleware have 🔑 next to them.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I see, thank you.


Expand Down Expand Up @@ -443,6 +611,11 @@ With `quiet` enabled, nothing except the initial startup information will be wri
quiet: true
```

Usage via the CLI
```
webpack-dev-server --quiet
```

## `devServer.setup`

`function`
Expand All @@ -458,6 +631,21 @@ setup(app){
}
```

## `devServer.socket`

`string`

The Unix socket to listen to (instead of a host).

```js
socket: 'socket'
```

Usage via the CLI
```
webpack-dev-server --socket socket
```


## `devServer.staticOptions`

Expand Down Expand Up @@ -488,6 +676,30 @@ For more information, see the [**stats documentation**](/configuration/stats).

T> This option has no effect when used with `quiet` or `noInfo`.

## `devServer.stdin` - CLI only

`boolean`

This option closes the server when stdin ends.

```
webpack-dev-server --stdin
```

## `devServer.useLocalIp`

`boolean`

This option lets the browser open with your local IP.

```js
useLocalIp: true
```

Usage via the CLI
```
webpack-dev-server --useLocalIp
```

## `devServer.watchContentBase`

Expand All @@ -501,6 +713,10 @@ watchContentBase: true

It is disabled by default.

Usage via the CLI
```
webpack-dev-server --watch-content-base
```

## `devServer.watchOptions` 🔑

Expand Down