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.
Using npm:
npm install koa-webpack@npm:@cbilotta/koa-webpack --save-dev
This fork targets Webpack 5.92.1 and webpack-dev-middleware 7.2.1. Use Node 18.12.0 or newer, as required by webpack-dev-middleware. Development checks use Node's built-in test runner as well as the existing AVA suite.
const Koa = require('koa');
const koaWebpack = require('koa-webpack');
const app = new Koa();
const options = { .. };
const middleware = await koaWebpack(options);
app.use(middleware);Returns a Promise which resolves the server middleware containing the
following additional properties:
close(callback)(Function) - Closes both the instance ofwebpack-dev-middlewareandwebpack-hot-client. Accepts a singleFunctioncallback parameter that is executed when complete.hotClient(Object) - An instance ofwebpack-hot-client.devMiddleware(Object) - An instance ofwebpack-dev-middleware
Install one middleware instance per compiler lifetime. Requests wait for a valid compilation without adding compiler hooks or uncancellable readiness callbacks per request. A fatal compiler failure rejects pending requests with the original error; another compilation attempt can recover. Ordinary compilation errors in stats are still handled by webpack-dev-middleware and the hot client.
Client disconnects reject pending work with ECONNABORTED. Closing the middleware
rejects pending and subsequent requests with ERR_MIDDLEWARE_CLOSED. Put your
application's error middleware before this middleware to choose HTTP feedback.
Cancellation prevents this adapter from starting downstream work or assigning a
late response; it cannot cancel application work that has already started.
Pass the original Koa context; do not replace ctx.req with a URL string. The
adapter supports that legacy workaround using ctx.request.req, but new callers
should leave the native request intact. Response headers, buffers, streams and
HEAD responses are adapted to Koa without replacing native response methods.
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:
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);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);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);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.
Use version 7 options such as stats; the old lazy and logLevel options are
not supported. Use devMiddleware.invalidate(callback) for explicit rebuilds.
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.
With this fork's Webpack 5 configuration, pass autoConfigure: false and configure
the hot-client entry and HotModuleReplacementPlugin in your Webpack config.
The hot client's legacy automatic entry rewriting expects Webpack 4 entry shapes.
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.
When serverSideRender is set to true in options.devMiddleware, compilation
stats are accessible from ctx.state.webpack.devMiddleware.stats.
app.use(async (ctx, next) => {
const assetsByChunkName = ctx.state.webpack.devMiddleware.stats.toJson().assetsByChunkName;
// do something with assetsByChunkName
})For more details please refer to: webpack-dev-middleware
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.context.outputFileSystem.createReadStream(filename)
});Please take a moment to read our contributing guidelines if you haven't yet done so.
This module started as a fork of
koa-webpack-middleware