1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
# koa-webpack [](https://travis-ci.org/shellscape/koa-webpack)
Development and Hot Module Reload Middleware for **Koa2**, in a single middleware module.
This module wraps and composes
[`webpack-dev-middleware`](https://github.com/webpack/webpack-dev-middleware) and
[`webpack-hot-client`](https://github.com/webpack-contrib/webpack-hot-client)
into a single middleware module, allowing for quick and concise implementation.
As an added bonus, it'll also use the installed `webpack` module from your project,
and the `webpack.config.js` file in the root of your project, automagically, should
you choose to let it. This negates the need for all of the repetitive setup and
config that you get with `koa-webpack-middleware`.
## Version 2 Breaking Changes
As of version 2.0.0, Node v4 is no longer supported. The minimum version of Node
supported is v6.11. Browser support is limited to those browsers which support
_native_ `WebSocket`. That typically means the last two major versions of a
browser. If you need support for older browsers, please use version 1.x of this
module. If you would like to submit a fix for a 1.x version of the module, please
submit that to the `1.x` branch.
### Migrating to Version 2.x
Version 1.x leveraged webpack-hot-middleware, which required the user to add an entry to the config for `webpack-hot-middleware/client`, and also add `webpack.HotModuleReplacementPlugin` to plugins. These are no longer needed, and will cause errors if not removed from the webpack config.
If you have setup `hot` options for `koa-webpack` in your config or code, you'll need to reference the [`webpack-hot-client` options](https://github.com/webpack-contrib/webpack-hot-client#options) and update those accordingly. The options for `webpack-hot-middleware` are _not_ 1:1 with `webpack-hot-client`
## Getting Started
First thing's first, install the module:
```bash
npm install koa-webpack --save-dev
```
If you happen to see warning from npm that reads:
`UNMET PEER DEPENDENCY webpack@2.1.0-beta.25` fear not, simply install the latest
beta version of `webpack`.
Next, setup the module in your code. (We're assuming ES6 syntax here)
```js
import Koa from 'koa';
import middleware from 'koa-webpack';
const app = new Koa();
app.use(middleware({
// options
}))
```
## API
### koaWebpack([options])
Returns an `Object` containing:
- `close(callback)` *(Function)* - Closes both the instance of `webpack-dev-middleware`
and `webpack-hot-client`. Accepts a single `Function` callback parameter that is
executed when complete.
- `client` *(Object)* - An instance of `webpack-hot-client`.
- `dev` *(Object)* - An instance of `webpack-dev-middleware`
## options
The middleware accepts an `options` Object, which can contain options for the
`webpack-dev-middleware` and `webpack-hot-client` bundled with this module.
The following is a property reference for the Object:
#### compiler
Type: `Object`
`optional`
Should you rather that the middleware use an instance of `webpack` that you've
already init'd [with webpack config], you can pass it to the middleware using
this option.
Example:
```js
import Webpack from 'webpack';
import config from './webpack.config.js';
const compiler = Webpack(config);
app.use(middleware({
compiler: compiler
}))
```
#### config
Type: `Object`
`optional`
Should you rather that the middleware use an instance of webpack configuration
that you've already required/imported, you can pass it to the middleware using
this option.
Example:
```js
import config from './webpack.config.js';
app.use(middleware({
config: config
}))
```
#### dev
Type: `Object`
`optional`
The `dev` property should contain options for `webpack-dev-middleware`, a list of
which is available at [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware).
Omitting this property will result in `webpack-dev-middleware` using its default
options.
#### hot
Type: `Object|Boolean`
`optional`
The `hot` property should contain options for `webpack-hot-client`, a list of
which is available at [webpack-hot-client](https://github.com/webpack-contrib/webpack-hot-client).
Omitting this property will result in `webpack-hot-client` using its default
options.
As of `v3.0.1` setting this to `false` will completely disable `webpack-hot-client`
and all automatic Hot Module Replacement functionality.
## Using with koa-compress
When using `koa-webpack` with [koa-compress](https://github.com/koajs/compress),
you may experience issues with saving files and hot module reload. Please review
[this issue](https://github.com/shellscape/koa-webpack/issues/36#issuecomment-289565573)
for more information and a workaround.
## Server-Side-Rendering
When `serverSideRender` is set to true in `config.dev`, `webpackStats` is accessible from `ctx.state.webpackStats`.
```js
app.use(async (ctx, next) => {
const assetsByChunkName = ctx.state.webpackStats.toJson().assetsByChunkName;
// do something with assetsByChunkName
})
```
For more details please refer to: [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware#server-side-rendering)
## Lint and test
```bash
npm install
npm run lint
npm test
```
## Contributing
We welcome your contributions! Please have a read of [CONTRIBUTING](CONTRIBUTING.md).
## Attribution
This module started as a fork of [`koa-webpack-middleware`](https://github.com/leecade/koa-webpack-middleware)
|
