0
# Configuration
1

2
Comprehensive configuration system that controls static file serving behavior, URL handling, custom headers, directory listings, and advanced routing patterns.
3

4
## Capabilities
5

6
### Configuration Object
7

8
The main configuration object that controls all aspects of the server behavior.
9

10
```javascript { .api }
11
interface Config {
12
  /** Directory path to serve files from (default: current working directory) */
13
  public?: string;
14
  /** Enable clean URLs by stripping .html extensions */
15
  cleanUrls?: boolean | string[];
16
  /** URL rewrite rules */
17
  rewrites?: RewriteRule[];
18
  /** URL redirect rules */
19
  redirects?: RedirectRule[];
20
  /** Custom header rules */
21
  headers?: HeaderRule[];
22
  /** Enable/configure directory listing */
23
  directoryListing?: boolean | string[];
24
  /** Files/patterns to exclude from directory listings */
25
  unlisted?: string[];
26
  /** Force trailing slash behavior on URLs */
27
  trailingSlash?: boolean;
28
  /** Render single file in directory instead of listing */
29
  renderSingle?: boolean;
30
  /** Follow symbolic links (default: false) */
31
  symlinks?: boolean;
32
  /** Use ETag headers instead of Last-Modified */
33
  etag?: boolean;
34
}
35
```
36

37
### Public Directory
38

39
Sets the root directory for serving files.
40

41
```javascript { .api }
42
public?: string;
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
// Serve from a subdirectory
49
await handler(req, res, {
50
  public: './dist'
51
});
52

53
// Serve from absolute path
54
await handler(req, res, {
55
  public: '/var/www/html'
56
});
57

58
// Serve Jekyll site
59
await handler(req, res, {
60
  public: '_site'
61
});
62
```
63

64
### Clean URLs
65

66
Enables clean URLs by automatically stripping `.html` extensions and performing redirects.
67

68
```javascript { .api }
69
cleanUrls?: boolean | string[];
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
// Enable for all HTML files
76
await handler(req, res, {
77
  cleanUrls: true
78
});
79

80
// Disable clean URLs
81
await handler(req, res, {
82
  cleanUrls: false
83
});
84

85
// Enable only for specific paths
86
await handler(req, res, {
87
  cleanUrls: ['/blog/**', '/docs/**']
88
});
89
```
90

91
### URL Rewrites
92

93
Transforms incoming request paths to different file system paths before serving.
94

95
```javascript { .api }
96
interface RewriteRule {
97
  /** Source pattern using glob syntax or path-to-regexp patterns */
98
  source: string;
99
  /** Target path or URL, can include captured parameters */
100
  destination: string;
101
}
102

103
rewrites?: RewriteRule[];
104
```
105

106
**Usage Examples:**
107

108
```javascript
109
await handler(req, res, {
110
  rewrites: [
111
    // API routes to specific files
112
    {
113
      source: '/api/**',
114
      destination: '/api.html'
115
    },
116
    // Dynamic routes with parameters
117
    {
118
      source: '/user/:id',
119
      destination: '/user.html?id=:id'
120
    },
121
    // Glob pattern matching
122
    {
123
      source: '/old-path/**',
124
      destination: '/new-path/$1'
125
    }
126
  ]
127
});
128
```
129

130
### URL Redirects
131

132
Sends HTTP redirects to different paths or external URLs.
133

134
```javascript { .api }
135
interface RedirectRule {
136
  /** Source pattern using glob syntax or path-to-regexp patterns */
137
  source: string;
138
  /** Target path or URL, can include captured parameters */
139
  destination: string;
140
  /** HTTP status code (default: 301) */
141
  type?: number;
142
}
143

144
redirects?: RedirectRule[];
145
```
146

147
**Usage Examples:**
148

149
```javascript
150
await handler(req, res, {
151
  redirects: [
152
    // Permanent redirect
153
    {
154
      source: '/old-page',
155
      destination: '/new-page',
156
      type: 301
157
    },
158
    // Temporary redirect
159
    {
160
      source: '/maintenance',
161
      destination: '/temp-page',
162
      type: 302
163
    },
164
    // External redirect
165
    {
166
      source: '/external',
167
      destination: 'https://example.com'
168
    },
169
    // Pattern-based redirect
170
    {
171
      source: '/blog/:slug',
172
      destination: '/posts/:slug'
173
    }
174
  ]
175
});
176
```
177

178
### Custom Headers
179

180
Applies custom HTTP headers based on path patterns.
181

182
```javascript { .api }
183
interface HeaderRule {
184
  /** Source pattern using glob syntax */
185
  source: string;
186
  /** Headers to apply */
187
  headers: Array<{
188
    key: string;
189
    value: string;
190
  }>;
191
}
192

193
headers?: HeaderRule[];
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
await handler(req, res, {
200
  headers: [
201
    // Cache static assets
202
    {
203
      source: '**/*.{js,css,png,jpg,gif}',
204
      headers: [{
205
        key: 'Cache-Control',
206
        value: 'max-age=31536000'
207
      }]
208
    },
209
    // Security headers for HTML
210
    {
211
      source: '**/*.html',
212
      headers: [
213
        {
214
          key: 'X-Frame-Options',
215
          value: 'DENY'
216
        },
217
        {
218
          key: 'X-Content-Type-Options',
219
          value: 'nosniff'
220
        }
221
      ]
222
    },
223
    // CORS headers for API
224
    {
225
      source: '/api/**',
226
      headers: [{
227
        key: 'Access-Control-Allow-Origin',
228
        value: '*'
229
      }]
230
    }
231
  ]
232
});
233
```
234

235
### Directory Listing
236

237
Controls directory listing behavior and appearance.
238

239
```javascript { .api }
240
directoryListing?: boolean | string[];
241
```
242

243
**Usage Examples:**
244

245
```javascript
246
// Enable directory listing for all directories
247
await handler(req, res, {
248
  directoryListing: true
249
});
250

251
// Disable directory listing
252
await handler(req, res, {
253
  directoryListing: false
254
});
255

256
// Enable only for specific paths
257
await handler(req, res, {
258
  directoryListing: ['/public/**', '/uploads/**']
259
});
260
```
261

262
### File Exclusion
263

264
Excludes files and directories from directory listings.
265

266
```javascript { .api }
267
unlisted?: string[];
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
await handler(req, res, {
274
  unlisted: [
275
    '.env',
276
    '.git',
277
    'node_modules',
278
    '*.log',
279
    'private/**'
280
  ]
281
});
282
```
283

284
### Trailing Slash
285

286
Forces consistent trailing slash behavior on URLs.
287

288
```javascript { .api }
289
trailingSlash?: boolean;
290
```
291

292
**Usage Examples:**
293

294
```javascript
295
// Force trailing slashes
296
await handler(req, res, {
297
  trailingSlash: true
298
});
299

300
// Remove trailing slashes
301
await handler(req, res, {
302
  trailingSlash: false
303
});
304
```
305

306
### Single File Rendering
307

308
When a directory contains only one file, serves that file directly instead of showing a directory listing.
309

310
```javascript { .api }
311
renderSingle?: boolean;
312
```
313

314
### Symbolic Links
315

316
Controls whether symbolic links are followed or result in 404 errors.
317

318
```javascript { .api }
319
symlinks?: boolean;
320
```
321

322
**Usage Examples:**
323

324
```javascript
325
// Follow symbolic links
326
await handler(req, res, {
327
  symlinks: true
328
});
329

330
// Block symbolic links (default, more secure)
331
await handler(req, res, {
332
  symlinks: false
333
});
334
```
335

336
### ETag Caching
337

338
Uses strong ETag headers instead of Last-Modified for better caching control.
339

340
```javascript { .api }
341
etag?: boolean;
342
```
343

344
**Usage Examples:**
345

346
```javascript
347
// Enable ETag caching
348
await handler(req, res, {
349
  etag: true
350
});
351

352
// Use Last-Modified headers (default)
353
await handler(req, res, {
354
  etag: false
355
});
356
```
357

358
### Complete Configuration Example
359

360
```javascript
361
const handler = require('serve-handler');
362

363
const config = {
364
  public: './public',
365
  cleanUrls: true,
366
  trailingSlash: false,
367
  etag: true,
368
  symlinks: false,
369
  renderSingle: true,
370
  
371
  rewrites: [
372
    {
373
      source: '/api/**',
374
      destination: '/api/index.html'
375
    }
376
  ],
377
  
378
  redirects: [
379
    {
380
      source: '/old-path',
381
      destination: '/new-path',
382
      type: 301
383
    }
384
  ],
385
  
386
  headers: [
387
    {
388
      source: '**/*.{js,css}',
389
      headers: [{
390
        key: 'Cache-Control',
391
        value: 'max-age=31536000'
392
      }]
393
    }
394
  ],
395
  
396
  directoryListing: ['/uploads/**'],
397
  
398
  unlisted: [
399
    '.DS_Store',
400
    '.git',
401
    'node_modules',
402
    '*.log'
403
  ]
404
};
405

406
await handler(request, response, config);
407
```