Skip to content

docs(dev-server): add transportMode docs and examples #3240

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
96 changes: 96 additions & 0 deletions src/content/configuration/dev-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -1359,6 +1359,102 @@ webpack-dev-server --stdin
```


## `devServer.transportMode`

`string = 'sockjs': 'sockjs' | 'ws'` `object`

W> `transportMode` is an experimental option, meaning its usage could potentially change without warning.

T> Providing a string to `devServer.transportMode` is a shortcut to setting both `devServer.transportMode.client` and `devServer.transportMode.server` to the given string value.

This option allows us either to choose the current `devServer` transport mode for client/server individually or to provide custom client/server implementation. This allows to specify how browser or other client communicates with the `devServer`.

The current default mode is [`'sockjs'`](https://www.npmjs.com/package/sockjs). This mode uses [SockJS-node](https://github.com/sockjs/sockjs-node) as a server, and [SockJS-client](https://www.npmjs.com/package/sockjs-client) on the client.

`'ws'` mode will become the default mode in the next major `devServer` version. This mode uses [ws](https://www.npmjs.com/package/ws) as a server, and native WebSockets on the client.

Use `'ws'` mode:

```javascript
module.exports = {
//...
devServer: {
transportMode: 'ws'
}
};
```

T> When providing a custom client and server implementation make sure that they are compatible with one another to communicate successfully.

### `devServer.transportMode.client`

`string` `path`

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).

Using path to `CustomClient.js`, a custom WebSocket client implementation, along with the compatible `'ws'` server:

```javascript
module.exports = {
//...
devServer: {
transportMode: {
client: require.resolve('./CustomClient'),
server: 'ws'
}
}
};
```

### `devServer.transportMode.server`

`string` `path` `function`

To create a custom server implementation, create a class that extends [`BaseServer`](https://github.com/webpack/webpack-dev-server/blob/master/lib/servers/BaseServer.js).

Using path to `CustomServer.js`, a custom WebSocket server implementation, along with the compatible `'ws'` client:

```javascript
module.exports = {
//...
devServer: {
transportMode: {
client: 'ws',
server: require.resolve('./CustomServer')
}
}
};
```

Using class exported by `CustomServer.js`, a custom WebSocket server implementation, along with the compatible `'ws'` client:

```javascript
module.exports = {
//...
devServer: {
transportMode: {
client: 'ws',
server: require('./CustomServer')
}
}
};
```

Using custom, compatible WebSocket client and server implementations:

```javascript
module.exports = {
//...
devServer: {
transportMode: {
client: require.resolve('./CustomClient'),
server: require.resolve('./CustomServer')
}
}
};
```


## `devServer.useLocalIp`

`boolean`
Expand Down