• This repository has been archived on 13/Jul/2021
  • Stars
    star
    121
  • Rank 293,924 (Top 6 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 7 years ago
  • Updated about 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

webpack HMR Client

npm node deps tests chat size

webpack-hot-client

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 Replacement Support.

Curious about the differences between this module and webpack-hot-middleware? Read more here.

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:

$ 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:

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, 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 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: <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.

The value of host.client can also be set to a wildcard character for Remote Machine Testing.

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 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: <Number>, server: <Number> }. 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 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. 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 documentation.

Remote Machine Testing

Please see the Remote Machine Testing documentation.

Contributing

We welcome your contributions! Please have a read of CONTRIBUTING for more information on how to get involved.

License

MIT

More Repositories

1

webpack-bundle-analyzer

Webpack plugin and CLI utility that represents bundle content as convenient interactive zoomable treemap
JavaScript
12,576
star
2

mini-css-extract-plugin

Lightweight CSS extraction plugin
JavaScript
4,654
star
3

awesome-webpack

A curated list of awesome Webpack resources, libraries and tools
HTML
4,588
star
4

css-loader

CSS Loader
JavaScript
4,300
star
5

extract-text-webpack-plugin

[DEPRECATED] Please use https://github.com/webpack-contrib/mini-css-extract-plugin Extracts text from a bundle into a separate file
JavaScript
4,014
star
6

sass-loader

Compiles Sass to CSS
JavaScript
3,899
star
7

postcss-loader

PostCSS loader for webpack
JavaScript
2,855
star
8

copy-webpack-plugin

Copy files and directories with webpack
JavaScript
2,836
star
9

webpack-hot-middleware

Webpack hot reloading you can attach to your own server
JavaScript
2,336
star
10

terser-webpack-plugin

Terser Plugin
JavaScript
1,939
star
11

file-loader

File Loader
JavaScript
1,861
star
12

style-loader

Style Loader
JavaScript
1,651
star
13

worker-loader

A webpack loader that registers a script as a Web Worker
JavaScript
1,455
star
14

install-webpack-plugin

Speed up development by automatically installing & saving dependencies with Webpack.
JavaScript
1,430
star
15

compression-webpack-plugin

Prepare compressed versions of assets to serve them with Content-Encoding
JavaScript
1,409
star
16

url-loader

A loader for webpack which transforms files into base64 URIs
JavaScript
1,403
star
17

uglifyjs-webpack-plugin

[deprecated] UglifyJS Plugin
JavaScript
1,382
star
18

html-loader

HTML Loader
JavaScript
1,164
star
19

thread-loader

Runs the following loaders in a worker pool
JavaScript
1,121
star
20

webpack-serve

Repository has moved:
JavaScript
1,092
star
21

eslint-loader

[DEPRECATED] A ESlint loader for webpack
JavaScript
1,057
star
22

less-loader

Compiles Less to CSS
JavaScript
956
star
23

raw-loader

A loader for webpack that allows importing files as a String
JavaScript
844
star
24

purifycss-webpack

UNMAINTAINED, use https://github.com/FullHuman/purgecss-webpack-plugin
JavaScript
772
star
25

bundle-loader

Bundle Loader
JavaScript
658
star
26

cache-loader

[DEPRECATED] Caches the result of following loaders on disk
JavaScript
638
star
27

expose-loader

Expose Loader
JavaScript
546
star
28

imports-loader

Imports Loader
JavaScript
519
star
29

stylus-loader

🎨 A stylus loader for webpack.
JavaScript
499
star
30

babel-minify-webpack-plugin

[DEPRECATED] Babel Minify Webpack Plugin
JavaScript
493
star
31

svg-inline-loader

Inline SVG loader with cleaning-up functionality
JavaScript
490
star
32

json-loader

json loader module for webpack - UNMAINTAINED
JavaScript
436
star
33

closure-webpack-plugin

Webpack Google Closure Compiler and Closure Library plugin -
JavaScript
434
star
34

stylelint-webpack-plugin

A Stylelint plugin for webpack
JavaScript
426
star
35

source-map-loader

extract sourceMappingURL comments from modules and offer it to webpack
JavaScript
362
star
36

script-loader

[deprecated] Script Loader
JavaScript
325
star
37

i18n-webpack-plugin

[DEPRECATED] Embed localization into your bundle
JavaScript
317
star
38

css-minimizer-webpack-plugin

cssnano plugin for Webpack
JavaScript
315
star
39

istanbul-instrumenter-loader

Istanbul Instrumenter Loader
JavaScript
273
star
40

grunt-webpack

integrate webpack into grunt build process
JavaScript
267
star
41

react-proxy-loader

Wraps a react component in a proxy component to enable Code Splitting.
JavaScript
259
star
42

eslint-webpack-plugin

A ESLint plugin for webpack
JavaScript
257
star
43

image-minimizer-webpack-plugin

Webpack loader and plugin to compress images using imagemin
JavaScript
235
star
44

exports-loader

Exports Loader
JavaScript
216
star
45

webpack-command

[DEPRECATED] Lightweight, modular, and opinionated webpack CLI that provides a superior experience
JavaScript
212
star
46

webpack-stylish

A stylish, optionated reporter for webpack
JavaScript
200
star
47

val-loader

val loader module for webpack
JavaScript
183
star
48

mocha-loader

Mocha Loader
JavaScript
146
star
49

null-loader

[DEPRECATED] A loader that returns an empty module (can still be used for webpack 4).
JavaScript
145
star
50

coffee-loader

CoffeeScript Loader
JavaScript
144
star
51

node-loader

node loader for native modules
JavaScript
117
star
52

transform-loader

transform loader for webpack
JavaScript
110
star
53

webpack-defaults

Defaults to be shared across webpack projects
JavaScript
108
star
54

json5-loader

[Deprecated] JSON5 loader for Webpack (can still be used for webpack 4)
JavaScript
72
star
55

jshint-loader

[DEPRECATED] jshint loader for webpack, please migrate on `eslint`
JavaScript
67
star
56

webpack-canary

Canary tooling for checking webpack dependencies against specific webpack versions
JavaScript
47
star
57

multi-loader

[DEPRECATED] A loader that splits a module into multiple modules loaded with different loaders.
JavaScript
44
star
58

webpack-log

[DEPRECATED] Please use logger API https://github.com/webpack/webpack/pull/9436
JavaScript
38
star
59

zopfli-webpack-plugin

[DEPRECATED] Prepare compressed versions of assets with node-zopfli
JavaScript
26
star
60

component-webpack-plugin

Use components with webpack - UNMAINTAINED
JavaScript
20
star
61

remark-loader

Load markdown through remark with image resolving and some react-specific features.
JavaScript
16
star
62

json-minimizer-webpack-plugin

JSON minimizer webpack plugin
JavaScript
15
star
63

gzip-loader

[DEPRECATED] gzip loader module for webpack
JavaScript
15
star
64

yaml-frontmatter-loader

[DEPRECATED] Yaml frontmatter loader
JavaScript
14
star
65

config-loader

[DEPRECATED] A loader for webpack configuration files
JavaScript
14
star
66

html-minimizer-webpack-plugin

HTML minimizer webpack plugin
JavaScript
14
star
67

organization

Applications, Standards & Documentation for webpack-contrib.
13
star
68

i18n-loader

i18n loader module for webpack - UNMAINTAINED
JavaScript
11
star
69

eslint-config-webpack

Webpack standard eslint configuration
JavaScript
10
star
70

coffee-redux-loader

coffee redux loader module for webpack - UNMAINTAINED
JavaScript
7
star
71

test-utils

webpack Loader/Plugin Test Helpers
JavaScript
6
star
72

coverjs-loader

coverjs loader module for webpack - UNMAINTAINED
JavaScript
4
star
73

circleci-node8

[DEPRECATED] Please migrate on azure pipelines. CircleCI 2.0 NodeJS 8 build container -
Dockerfile
3
star
74

restyle-loader

[DEPRECATED] Use https://github.com/danielverejan/restyle-loader
JavaScript
3
star
75

tag-versions

A commandline wrapper around omichelsen/compare-versions to compare dist-tags
JavaScript
2
star
76

circleci-node-base

CircleCI 2.0 base build container -
Dockerfile
1
star
77

babel-preset-webpack

[DEPRECATED] Webpack Organization es2015 Babel Preset - See:
JavaScript
1
star
78

circleci-node9

[DEPRECATED] Please migrate on azure pipelines. CircleCI 2.0 NodeJS 9 build container -
Dockerfile
1
star
79

circleci-node-jdk8

Deprecated, use ->
1
star
80

cli-utils

[DEPRECATED] A suite of utilities for webpack projects which expose a CLI
JavaScript
1
star