koa-webpack

Development and Hot Module Reload Middleware for Koa2, in a single middleware module.

This module wraps and composes webpack-dev-middleware and 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 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:

npm install koa-webpack --save-dev

If you happen to see warning from npm that reads: UNMET PEER DEPENDENCY [email protected] fear not, simply install the latest beta version of webpack.

Next, setup the module in your code. (We're assuming ES6 syntax here)

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:

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:

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. 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. 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, you may experience issues with saving files and hot module reload. Please review this issue 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.

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

Lint and test

npm install
npm run lint
npm test

Contributing

We welcome your contributions! Please have a read of CONTRIBUTING.

Attribution

This module started as a fork of koa-webpack-middleware