Awesome
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
.
Install
Using npm:
npm install koa-webpack --save-dev
<a href="https://www.patreon.com/shellscape">
<img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
</a>
Requirements
koa-webpack
is an evergreen module. 🌲 This module requires an Active LTS Node version (v8.0.0+ or v10.0.0+), and Webpack v4.0.0+.
Usage
const Koa = require('koa');
const koaWebpack = require('koa-webpack');
const app = new Koa();
const options = { .. };
const middleware = await koaWebpack(options);
app.use(middleware);
API
koaWebpack([options])
Returns a Promise
which resolves the server middleware
containing the
following additional properties:
close(callback)
(Function) - Closes both the instance ofwebpack-dev-middleware
andwebpack-hot-client
. Accepts a singleFunction
callback parameter that is executed when complete.hotClient
(Object) - An instance ofwebpack-hot-client
.devMiddleware
(Object) - An instance ofwebpack-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:
const webpack = require('webpack');
const config = require('./webpack.config.js');
const koaWebpack = require('koa-webpack');
const compiler = webpack(config);
const middleware = await koaWebpack({ compiler });
app.use(middleware);
config
Type: Object
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:
const koaWebpack = require('koa-webpack');
const config = require('./webpack.config.js');
const middleware = await koaWebpack({ config });
app.use(middleware);
configPath
Type: String
Allows you to specify the absolute path to the Webpack config file to be used.
Example:
const path = require('path');
const koaWebpack = require('koa-webpack');
// The Webpack config file would be at "./client/webpack.config.js".
const middleware = await koaWebpack({
configPath: path.join(__dirname, 'client', 'webpack.config.js')
});
app.use(middleware);
devMiddleware
Type: Object
The devMiddleware
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.
hotClient
Type: Object|Boolean
The hotClient
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.devMiddleware
, 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
Using with html-webpack-plugin
When using with html-webpack-plugin, you can access dev-middleware in-memory filesystem to serve index.html file:
const middleware = await koaWebpack({ config });
app.use(middleware);
app.use(async (ctx) => {
const filename = path.resolve(webpackConfig.output.path, 'index.html')
ctx.response.type = 'html'
ctx.response.body = middleware.devMiddleware.fileSystem.createReadStream(filename)
});
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
CONTRIBUTING
Attribution
This module started as a fork of
koa-webpack-middleware