Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/webpack-contrib/webpack-hot-client

webpack HMR Client
https://github.com/webpack-contrib/webpack-hot-client

client hmr hot-module-replacement webpack websockets

Last synced: 3 months ago
JSON representation

webpack HMR Client

Awesome Lists containing this project

README 

        


  

    

  




[![npm][npm]][npm-url]

[![node][node]][node-url]

[![deps][deps]][deps-url]

[![tests][tests]][tests-url]

[![chat][chat]][chat-url]

[![size][size]][size-url]



# webpack-hot-client



A client for enabling, and interacting with, webpack [Hot Module Replacement][hmr-docs].



This is intended to work in concert with [`webpack-dev-middleware`][dev-middleware]

and allows for adding Hot Module Replacement to an existing server, without a

dependency upon [`webpack-dev-server`][dev-server]. This comes in handy for testing

in projects that already use server frameworks such as `Express` or `Koa`.



`webpack-hot-client` accomplishes this by creating a `WebSocket` server, providing

the necessary client (browser) scripts that communicate via `WebSocket`s, and

automagically adding the necessary webpack plugins and config entries. All of

that allows for a seamless integration of Hot Module Replacement Support.



Curious about the differences between this module and `webpack-hot-middleware`?

[Read more here](https://github.com/webpack-contrib/webpack-hot-client/issues/18).



## Requirements



This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.



## Getting Started



To begin, you'll need to install `webpack-hot-client`:



```console

$ npm install webpack-hot-client --save-dev

```



## Gotchas



### Entries



In order to use `webpack-hot-client`, your `webpack` config should include an

`entry` option that is set to an `Array` of `String`, or an `Object` who's keys

are set to an `Array` of `String`. You may also use a `Function`, but that

function should return a value in one of the two valid formats.



This is primarily due to restrictions in `webpack` itself and the way that it

processes options and entries. For users of webpack v4+ that go the zero-config

route, you must specify an `entry` option.



### Automagical Configuration



As a convenience `webpack-hot-client` adds `HotModuleReplacementPlugin`

and the necessary entries to your `webpack` config for you at runtime. Including

the plugin in your config manually while using this module may produce unexpected

or wonky results. If you have a need to configure entries and plugins for HMR

manually, use the `autoConfigure` option.



### Best Practices



When using this module manually, along with the default `port` option value of

`0`, starting compilation (or passing a compiler to `webpack-dev-middleware`)

should be done _after_ the socket server has finished listening and allocating

a port. This ensures that the build will contain the allocated port. (See the

Express example below.) This condition does not apply if providing a static

`port` option to the API.



### Express



For setting up the module for use with an `Express` server, try the following:



```js

const hotClient = require('webpack-hot-client');

const middleware = require('webpack-dev-middleware');

const webpack = require('webpack');

const config = require('./webpack.config');



const compiler = webpack(config);

const { publicPath } = config.output;

const options = { ... }; // webpack-hot-client options



// we recommend calling the client _before_ adding the dev middleware

const client = hotClient(compiler, options);

const { server } = client;



server.on('listening', () => {

  app.use(middleware(compiler, { publicPath }));

});

```



### Koa



Since `Koa`@2.0.0 was released, the patterns and requirements for using

`webpack-dev-middleware` have changed somewhat, due to use of `async/await` in

Koa. As such, one potential solution is to use [`koa-webpack`][koa-webpack],

which wires up the dev middleware properly for Koa, and also implements this

module. If you'd like to use both modules without `koa-webpack`, you may examine

that module's code for implementation details.



## Browser Support



Because this module leverages _native_ `WebSockets`, the browser support for this

module is limited to only those browsers which support native `WebSocket`. That

typically means the last two major versions of a particular browser.



Please visit [caniuse.com](https://caniuse.com/#feat=websockets) for a full

compatibility table.



_Note: We won't be accepting requests for changes to this facet of the module._



## API



### client(compiler, [options])



Returns an `Object` containing:



- `close()` *(Function)* - Closes the WebSocketServer started by the module.

- `wss` *(WebSocketServer)* - A WebSocketServer instance.



#### options



Type: `Object`



##### allEntries



Type: `Boolean`  

Default: `false`



If true and `autoConfigure` is true, will automatically configures each `entry`

key for the webpack compiler. Typically used when working with or manipulating

different chunks in the same compiler configuration.



##### autoConfigure



Type: `Boolean`  

Default: `true`



If true, automatically configures the `entry` for the webpack compiler, and adds

the `HotModuleReplacementPlugin` to the compiler.



##### host



Type: `String|Object`  

Default: `'localhost'`



Sets the host that the `WebSocket` server will listen on. If this doesn't match

the host of the server the module is used with, the module may not function

properly. If the `server` option is defined, and the server has been instructed

to listen, this option is ignored.



If using the module in a specialized environment, you may choose to specify an

`object` to define `client` and `server` host separately. The `object` value

should match `{ client: , server:  }`. Be aware that the `client`

host will be used _in the browser_ by `WebSockets`. You should not use this

option in this way unless _you know what you're doing._ Using a mismatched

`client` and `server` host will be **unsupported by the project** as the behavior

in the browser can be unpredictable and is specific to a particular environment.



The value of `host.client` can also be set to a wildcard character for

[Remote Machine Testing](./docs/REMOTE.md).



##### hmr



Type: `Boolean`  

Default: `true`



If true, instructs the client script to attempt Hot Module Replacement patching

of modules.



##### https



Type: `Boolean`  

Default: `false`



If true, instructs the client script to use `wss://` as the `WebSocket` protocol.



When using the `server` option and passing an instance of `https.Server`, this

flag must also be true. Otherwise, the sockets cannot communicate and this

module won't function properly. The module will examine the `server` instance

passed and if `server` _is an instance of `https.Server`, and `https` is not

already set_, will set `https` to `true`.



_Note: When using a self-signed certificate on Firefox, you must add a "Server

Exception" for `localhost:{port}` where `{port}` is either the `port` or the

`port.server` option for secure `WebSocket` to work correctly._



##### logLevel



Type: `String`  

Default: `'info'`



Sets the minimum level of logs that will be displayed in the console. Please see

[webpack-log/#levels][levels] for valid values.



##### logTime



Type: `Boolean`  

Default: `false`



If true, instructs the internal logger to prepend log output with a timestamp.



##### port



Type: `Number|Object`  

Default: `0`



The port the `WebSocket` server should listen on. By default, the socket server

will allocate a port. If a different port is chosen, the consumer of the module

must ensure that the port is free before hand. If the `server` option is defined,

and the server has been instructed to listen, this option is ignored.



If using the module in a specialized environment, you may choose to specify an

`object` to define `client` and `server` port separately. The `object` value

should match `{ client: , server:  }`. Be aware that the `client`

port will be used _in the browser_ by `WebSockets`. You should not use this

option in this way unless _you know what you're doing._ Using a mismatched

`client` and `server` port will be **unsupported by the project** as the behavior

in the browser can be unpredictable and is specific to a particular environment.



##### reload



Type: `Boolean`  

Default: `true`



If true, instructs the browser to physically refresh the entire page if / when

webpack indicates that a hot patch cannot be applied and a full refresh is needed.



This option also instructs the browser whether or not to refresh the entire page

when `hmr: false` is used.



_Note: If both `hmr` and `reload` are false, and these are permanent settings,

it makes this module fairly useless._



##### server



Type: `Object`  

Default: `null`



If a server instance (eg. Express or Koa) is provided, the `WebSocket` server

will attempt to attach to the server instance instead of using a separate port.



##### stats



Type: `Object`  

Default: `{ context: process.cwd() }`



An object specifying the webpack [stats][stats] configuration. This does not

typically need to be modified.



##### validTargets



Type: `Array[String]`

Default: `['web']`



By default, `webpack-hot-client` is meant to, and expects to function on the

[`'web'` build target](https://webpack.js.org/configuration/target). However,

you can manipulate this by adding targets to this property. eg.



```

  // will be merged with the default 'web' target

  validTargets: ['batmobile']

```



## Communicating with Client WebSockets



Please see the [WebSockets](./docs/WEBSOCKETS.md) documentation.



## Remote Machine Testing



Please see the [Remote Machine Testing](./docs/REMOTE.md) documentation.



## Contributing



We welcome your contributions! Please have a read of

[CONTRIBUTING](./.github/CONTRIBUTING.md) for more information on how to get involved.



## License



#### [MIT](./LICENSE)



[npm]: https://img.shields.io/npm/v/webpack-hot-client.svg

[npm-url]: https://npmjs.com/package/webpack-hot-client



[node]: https://img.shields.io/node/v/webpack-hot-client.svg

[node-url]: https://nodejs.org



[deps]: https://david-dm.org/webpack-contrib/webpack-hot-client.svg

[deps-url]: https://david-dm.org/webpack-contrib/webpack-hot-client



[tests]: 	https://img.shields.io/circleci/project/github/webpack-contrib/webpack-hot-client.svg

[tests-url]: https://circleci.com/gh/webpack-contrib/webpack-hot-client



[cover]: https://codecov.io/gh/webpack-contrib/webpack-hot-client/branch/master/graph/badge.svg

[cover-url]: https://codecov.io/gh/webpack-contrib/webpack-hot-client



[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg

[chat-url]: https://gitter.im/webpack/webpack



[size]: https://packagephobia.now.sh/badge?p=webpack-hot-client

[size-url]: https://packagephobia.now.sh/result?p=webpack-hot-client



[dev-middleware]: https://github.com/webpack/webpack-dev-middleware

[dev-server]: https://github.com/webpack/webpack-dev-server

[hmr-docs]: https://webpack.js.org/concepts/hot-module-replacement/

[koa-webpack]: https://github.com/shellscape/koa-webpack

[levels]: https://github.com/webpack-contrib/webpack-log#level

[stats]: https://webpack.js.org/configuration/stats/#stats