A client for enabling, and interacting with, webpack Hot Module Replacement.
This is intended to work in concert with webpack-dev-middleware
and allows for adding Hot Module Replacement to an existing server, without a
dependency upon webpack-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 WebSockets, and
automagically adding the necessary webpack plugins and config entries. All of
that allows for a seamless integration of Hot Module Support.
Curious about the differences between this module and webpack-hot-middleware?
Read more here.
To begin, you'll need to install webpack-hot-client:
$ npm install webpack-hot-client --save-devIn 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.
For setting up the module for use with an Express server, try the following:
const client = 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
client(compiler, options);
app.use(middleware(compiler, { publicPath }));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,
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.
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.
Note: We won't be accepting requests for changes to this facet of the module.
Returns an Object containing:
close()(Function) - Closes the WebSocketServer started by the module.wss(WebSocketServer) - A WebSocketServer instance.
Type: Object
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, 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: <String>, server: <String> }. 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.
Type: Boolean
Default: true
If true, instructs the client script to attempt hot patching of modules.
Type: Boolean
Default: false
If true, instructs the client script to use wss:// as the WebSocket protocol.
If you're using a server setup with HTTPS, you must set this to true or the
sockets cannot communicate and this module won't function properly.
Type: String
Default: 'info'
Sets the minimum level of logs that will be displayed in the console. Please see webpack-log/#levels for valid values.
Type: Boolean
Default: false
If true, instructs the internal logger to prepend log output with a timestamp.
Type: Number
Default: 8081
The port the WebSocket server should listen on. It's recommended that a
server instance is passed to assure there aren't any port conflicts.
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 hot: false is used.
Note: If both hot and reload are false, and these are permanent settings,
it makes this module fairly useless.
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.
Type: Object
Default: { context: process.cwd() }
An object specifying the webpack stats configuration. This does not typically need to be modified.
By default, webpack-hot-client is meant to, and expects to function on the
'web' build target. However,
you can manipulate this by setting the WHC_TARGET environment variable. eg.
$ export WHC_TARGET=electon-renderer; webpack-serve ...Or by setting process.env.WHC_TARGET before executing the API.
Note: Changing this value is allowed but is unsupported.
In some rare situations, you may have the need to communicate with the attached
WebSockets in the browser. To accomplish this, open a new WebSocket to the
server, and send a broadcast message. eg.
const stringify = require('json-stringify-safe');
const { WebSocket } = require('ws');
const socket = new WebSocket('ws://localhost:8081'); // this should match the server settings
const data = {
type: 'broadcast',
data: { // the message you want to broadcast
type: '<something fun>', // the message type you want to broadcast
data: { ... } // the message data you want to broadcast
}
};
socket.send(stringify(data));Note: The data property of the message should contain the enveloped message
you wish to broadcast to all other client WebSockets.
We welcome your contributions! Please have a read of CONTRIBUTING.md for more information on how to get involved.