0
# Framework Integration
1

2
webpack-dev-middleware provides built-in adapters for popular Node.js frameworks beyond Express, enabling native integration patterns for Hapi.js, Koa.js, and Hono.
3

4
## Hapi.js Integration
5

6
### hapiWrapper
7

8
```javascript { .api }
9
function hapiWrapper<HapiServer, HapiOptionsInternal>(): HapiPlugin<HapiServer, HapiOptionsInternal>;
10
```
11

12
Creates a Hapi.js plugin for webpack-dev-middleware integration.
13

14
**Returns:** Hapi plugin object with registration method
15

16
### Usage Example
17

18
```javascript
19
const Hapi = require("@hapi/hapi");
20
const webpack = require("webpack");
21
const webpackDevMiddleware = require("webpack-dev-middleware");
22

23
const server = Hapi.server({ port: 3000 });
24

25
await server.register({
26
  plugin: webpackDevMiddleware.hapiWrapper(),
27
  options: {
28
    compiler: webpack(webpackConfig),
29
    publicPath: "/assets/",
30
    stats: "minimal"
31
  }
32
});
33

34
// Access middleware via server decoration
35
server.webpackDevMiddleware.waitUntilValid(() => {
36
  console.log("Webpack ready");
37
});
38

39
await server.start();
40
```
41

42
## Koa.js Integration
43

44
### koaWrapper
45

46
```javascript { .api }
47
function koaWrapper<RequestInternal, ResponseInternal>(
48
  compiler: Compiler | MultiCompiler,
49
  options?: Options<RequestInternal, ResponseInternal>
50
): KoaMiddleware<RequestInternal, ResponseInternal>;
51
```
52

53
Creates Koa.js compatible middleware that adapts request/response handling.
54

55
**Parameters:**
56
- `compiler`: Webpack compiler instance
57
- `options`: Optional middleware configuration
58

59
**Returns:** Koa middleware function with `devMiddleware` property
60

61
### Usage Example
62

63
```javascript
64
const Koa = require("koa");
65
const webpack = require("webpack");
66
const webpackDevMiddleware = require("webpack-dev-middleware");
67

68
const app = new Koa();
69
const compiler = webpack(webpackConfig);
70

71
const middleware = webpackDevMiddleware.koaWrapper(compiler, {
72
  publicPath: "/assets/",
73
  stats: "minimal"
74
});
75

76
app.use(middleware);
77

78
// Access underlying middleware
79
middleware.devMiddleware.waitUntilValid(() => {
80
  console.log("Webpack ready");
81
});
82

83
app.listen(3000);
84
```
85

86
## Hono Integration
87

88
### honoWrapper
89

90
```javascript { .api }
91
function honoWrapper<RequestInternal, ResponseInternal>(
92
  compiler: Compiler | MultiCompiler, 
93
  options?: Options<RequestInternal, ResponseInternal>
94
): HonoMiddleware<RequestInternal, ResponseInternal>;
95
```
96

97
Creates Hono framework compatible middleware with proper context handling.
98

99
**Parameters:**
100
- `compiler`: Webpack compiler instance
101
- `options`: Optional middleware configuration
102

103
**Returns:** Hono middleware function with `devMiddleware` property
104

105
### Usage Example
106

107
```javascript
108
import { Hono } from "hono";
109
import { serve } from "@hono/node-server";
110
import webpack from "webpack";
111
import webpackDevMiddleware from "webpack-dev-middleware";
112

113
const app = new Hono();
114
const compiler = webpack(webpackConfig);
115

116
const middleware = webpackDevMiddleware.honoWrapper(compiler, {
117
  publicPath: "/assets/",
118
  stats: "minimal"
119
});
120

121
app.use("*", middleware);
122

123
// Access underlying middleware
124
middleware.devMiddleware.waitUntilValid(() => {
125
  console.log("Webpack ready");
126
});
127

128
serve({ fetch: app.fetch, port: 3000 });
129
```
130

131
## Type Definitions
132

133
### Plugin Interfaces
134

135
```javascript { .api }
136
interface HapiPlugin<S, O> {
137
  pkg: { name: string };
138
  multiple: boolean;
139
  register: (server: S, options: O) => void | Promise<void>;
140
}
141

142
interface HapiOptions extends Options {
143
  compiler: Compiler | MultiCompiler;
144
}
145
```
146

147
### Framework-Specific Properties
148

149
```javascript { .api }
150
// Koa middleware interface with devMiddleware property
151
interface KoaMiddleware<RequestInternal, ResponseInternal> {
152
  devMiddleware: API<RequestInternal, ResponseInternal>;
153
  (ctx: any, next: Function): Promise<void> | void;
154
}
155

156
// Hono middleware interface with devMiddleware property  
157
interface HonoMiddleware<RequestInternal, ResponseInternal> {
158
  devMiddleware: API<RequestInternal, ResponseInternal>;
159
  (ctx: any, next: Function): Promise<void> | void;
160
}
161
```
162

163
## Framework Compatibility
164

165
### Express and Connect
166

167
Direct middleware usage (no wrapper needed):
168

169
```javascript
170
const express = require("express");
171
const connect = require("connect");
172

173
// Express
174
app.use(webpackDevMiddleware(compiler, options));
175

176
// Connect
177
const app = connect();
178
app.use(webpackDevMiddleware(compiler, options));
179
```
180

181
### Fastify
182

183
Via Express compatibility plugin:
184

185
```javascript
186
const fastify = require("fastify")();
187

188
await fastify.register(require("@fastify/express"));
189
fastify.use(webpackDevMiddleware(compiler, options));
190
```
191

192
### Raw Node.js HTTP
193

194
Direct integration with Node.js HTTP server:
195

196
```javascript
197
const http = require("http");
198
const middleware = webpackDevMiddleware(compiler, options);
199

200
const server = http.createServer((req, res) => {
201
  middleware(req, res, (err) => {
202
    if (err) {
203
      res.statusCode = 500;
204
      res.end("Internal Server Error");
205
    } else {
206
      res.statusCode = 404;
207
      res.end("Not Found");
208
    }
209
  });
210
});
211
```
212

213
## Error Handling
214

215
All framework wrappers include proper error handling:
216

217
```javascript
218
// Errors are passed to framework-specific error handlers
219
try {
220
  await middleware(ctx, next);
221
} catch (err) {
222
  // Framework-appropriate error response
223
  ctx.status = err.statusCode || err.status || 500;
224
  ctx.body = { message: err.message };
225
}
226
```
227

228
## Context Integration
229

230
Framework wrappers properly integrate with each framework's request/response context:
231

232
- **Hapi**: Decorates server with `webpackDevMiddleware` property
233
- **Koa**: Adapts `ctx.req`/`ctx.res` and manages `ctx.status`/`ctx.body`
234
- **Hono**: Integrates with Hono's context object and response handling