0
# Configuration Options
1

2
webpack-dev-middleware provides comprehensive configuration options for controlling file serving behavior, HTTP headers, caching, and development features.
3

4
## Options Interface
5

6
```javascript { .api }
7
interface Options<RequestInternal, ResponseInternal> {
8
  mimeTypes?: { [key: string]: string };
9
  mimeTypeDefault?: string;
10
  writeToDisk?: boolean | ((targetPath: string) => boolean);
11
  methods?: string[];
12
  headers?: Headers<RequestInternal, ResponseInternal>;
13
  publicPath?: string | Function;
14
  stats?: Configuration["stats"];
15
  serverSideRender?: boolean;
16
  outputFileSystem?: OutputFileSystem;
17
  index?: boolean | string;
18
  modifyResponseData?: ModifyResponseData<RequestInternal, ResponseInternal>;
19
  etag?: "weak" | "strong";
20
  lastModified?: boolean;
21
  cacheControl?: boolean | number | string | CacheControlObject;
22
  cacheImmutable?: boolean;
23
}
24
```
25

26
## File Serving Options
27

28
### mimeTypes
29

30
```javascript { .api }
31
mimeTypes?: { [key: string]: string };
32
```
33

34
Custom MIME type mappings for file extensions.
35

36
**Default:** `undefined`
37

38
**Example:**
39
```javascript
40
{
41
  mimeTypes: {
42
    ".custom": "application/x-custom",
43
    ".special": "text/special"
44
  }
45
}
46
```
47

48
### mimeTypeDefault
49

50
```javascript { .api }
51
mimeTypeDefault?: string;
52
```
53

54
Default MIME type when content type cannot be determined.
55

56
**Default:** `undefined`
57

58
**Example:**
59
```javascript
60
{
61
  mimeTypeDefault: "application/octet-stream"
62
}
63
```
64

65
### index
66

67
```javascript { .api }
68
index?: boolean | string;
69
```
70

71
Controls index file serving for directory requests.
72

73
**Default:** `"index.html"`
74

75
**Options:**
76
- `false`: Disable index serving
77
- `true`: Use default "index.html"
78
- `string`: Custom index filename
79

80
**Example:**
81
```javascript
82
{
83
  index: "main.html"  // Serve main.html for directory requests
84
}
85
```
86

87
### publicPath
88

89
```javascript { .api }
90
publicPath?: string | Function;
91
```
92

93
The public URL path where files are served.
94

95
**Default:** Webpack configuration `output.publicPath`
96

97
**Example:**
98
```javascript
99
{
100
  publicPath: "/assets/"  // Serve files under /assets/ path
101
}
102
```
103

104
## HTTP Configuration
105

106
### methods
107

108
```javascript { .api }
109
methods?: string[];
110
```
111

112
HTTP methods accepted by the middleware.
113

114
**Default:** `["GET", "HEAD"]`
115

116
**Example:**
117
```javascript
118
{
119
  methods: ["GET", "HEAD", "POST"]
120
}
121
```
122

123
### headers
124

125
```javascript { .api }
126
headers?: Headers<RequestInternal, ResponseInternal>;
127

128
type Headers<RequestInternal, ResponseInternal> = 
129
  | NormalizedHeaders
130
  | ((req: RequestInternal, res: ResponseInternal, context: Context) => void | undefined | NormalizedHeaders)
131
  | undefined;
132

133
type NormalizedHeaders = 
134
  | Record<string, string | number>
135
  | Array<{ key: string; value: number | string }>;
136
```
137

138
Custom HTTP headers for responses.
139

140
**Default:** `undefined`
141

142
**Examples:**
143
```javascript
144
// Object format
145
{
146
  headers: {
147
    "X-Custom-Header": "value",
148
    "Cache-Control": "no-cache"
149
  }
150
}
151

152
// Array format
153
{
154
  headers: [
155
    { key: "X-Custom-Header", value: "value" },
156
    { key: "Cache-Control", value: "no-cache" }
157
  ]
158
}
159

160
// Function format
161
{
162
  headers: (req, res, context) => {
163
    if (context.stats && context.stats.hasErrors()) {
164
      return { "X-Build-Status": "error" };
165
    }
166
    return { "X-Build-Status": "success" };
167
  }
168
}
169
```
170

171
## Caching Options
172

173
### etag
174

175
```javascript { .api }
176
etag?: "weak" | "strong";
177
```
178

179
Enable and configure ETag generation.
180

181
**Default:** `undefined` (disabled)
182

183
**Example:**
184
```javascript
185
{
186
  etag: "weak"  // Generate weak ETags
187
}
188
```
189

190
### lastModified
191

192
```javascript { .api }
193
lastModified?: boolean;
194
```
195

196
Enable Last-Modified headers based on file modification time.
197

198
**Default:** `undefined` (disabled)
199

200
**Example:**
201
```javascript
202
{
203
  lastModified: true
204
}
205
```
206

207
### cacheControl
208

209
```javascript { .api }
210
cacheControl?: boolean | number | string | CacheControlObject;
211

212
interface CacheControlObject {
213
  maxAge?: number;
214
  immutable?: boolean;
215
}
216
```
217

218
Configure Cache-Control header.
219

220
**Default:** `undefined`
221

222
**Examples:**
223
```javascript
224
// Boolean
225
{ cacheControl: false }  // Disable caching
226

227
// Number (max-age in seconds)
228
{ cacheControl: 3600 }  // Cache for 1 hour
229

230
// String
231
{ cacheControl: "no-cache, no-store" }
232

233
// Object
234
{
235
  cacheControl: {
236
    maxAge: 86400,    // 24 hours
237
    immutable: true
238
  }
239
}
240
```
241

242
### cacheImmutable
243

244
```javascript { .api }
245
cacheImmutable?: boolean;
246
```
247

248
Enable immutable caching for assets with hashes in filenames.
249

250
**Default:** `undefined`
251

252
**Example:**
253
```javascript
254
{
255
  cacheImmutable: true  // Add immutable directive for hashed assets
256
}
257
```
258

259
## Development Options
260

261
### writeToDisk
262

263
```javascript { .api }
264
writeToDisk?: boolean | ((targetPath: string) => boolean);
265
```
266

267
Write files to disk in addition to serving from memory.
268

269
**Default:** `false`
270

271
**Examples:**
272
```javascript
273
// Write all files to disk
274
{ writeToDisk: true }
275

276
// Selective file writing
277
{
278
  writeToDisk: (targetPath) => {
279
    return targetPath.endsWith('.html');  // Only write HTML files
280
  }
281
}
282
```
283

284
### serverSideRender
285

286
```javascript { .api }
287
serverSideRender?: boolean;
288
```
289

290
Enable server-side rendering mode (disables serving static files).
291

292
**Default:** `undefined`
293

294
**Example:**
295
```javascript
296
{
297
  serverSideRender: true  // Only provide stats, don't serve files
298
}
299
```
300

301
### stats
302

303
```javascript { .api }
304
stats?: Configuration["stats"];
305
```
306

307
Webpack stats configuration for build output.
308

309
**Default:** Webpack configuration stats
310

311
**Examples:**
312
```javascript
313
// Preset
314
{ stats: "minimal" }
315

316
// Boolean
317
{ stats: false }  // Disable stats output
318

319
// Object
320
{
321
  stats: {
322
    colors: true,
323
    modules: false,
324
    chunks: false
325
  }
326
}
327
```
328

329
## Advanced Options
330

331
### outputFileSystem
332

333
```javascript { .api }
334
outputFileSystem?: OutputFileSystem;
335
```
336

337
Custom file system for webpack output.
338

339
**Default:** `memfs` (memory file system)
340

341
**Example:**
342
```javascript
343
const fs = require("fs");
344

345
{
346
  outputFileSystem: fs  // Use real file system
347
}
348
```
349

350
### modifyResponseData
351

352
```javascript { .api }
353
modifyResponseData?: ModifyResponseData<RequestInternal, ResponseInternal>;
354

355
type ModifyResponseData<RequestInternal, ResponseInternal> = (
356
  req: RequestInternal,
357
  res: ResponseInternal,
358
  data: Buffer | ReadStream,
359
  byteLength: number
360
) => ResponseData;
361

362
interface ResponseData {
363
  data: Buffer | ReadStream;
364
  byteLength: number;
365
}
366
```
367

368
Callback to modify response data before sending.
369

370
**Example:**
371
```javascript
372
{
373
  modifyResponseData: (req, res, data, byteLength) => {
374
    if (req.url.endsWith('.js')) {
375
      // Add source map comment
376
      const modified = Buffer.concat([
377
        data,
378
        Buffer.from('\n//# sourceMappingURL=bundle.js.map')
379
      ]);
380
      return {
381
        data: modified,
382
        byteLength: modified.length
383
      };
384
    }
385
    return { data, byteLength };
386
  }
387
}
388
```
389

390
## Configuration Examples
391

392
### Production-like Development
393

394
```javascript
395
{
396
  publicPath: "/assets/",
397
  stats: "errors-warnings",
398
  headers: {
399
    "Cache-Control": "no-cache"
400
  },
401
  etag: "strong",
402
  lastModified: true
403
}
404
```
405

406
### Hot Module Replacement Setup
407

408
```javascript
409
{
410
  publicPath: "/",
411
  stats: "minimal",
412
  headers: {
413
    "Access-Control-Allow-Origin": "*"
414
  },
415
  writeToDisk: false
416
}
417
```
418

419
### Custom File System Integration
420

421
```javascript
422
{
423
  outputFileSystem: customMemoryFS,
424
  writeToDisk: (targetPath) => {
425
    return targetPath.includes('critical');
426
  },
427
  modifyResponseData: (req, res, data) => {
428
    // Transform data before serving
429
    return { data: transformData(data), byteLength: data.length };
430
  }
431
}
432
```