0
# Configuration Options
1

2
Comprehensive configuration system supporting caching, security, performance, and behavior customization for the st static file server.
3

4
## Capabilities
5

6
### Main Options Interface
7

8
Core configuration options for the st static file server.
9

10
```javascript { .api }
11
interface StOptions {
12
  /** Filesystem path to serve files from (required) */
13
  path: string;
14
  /** URL mount point (default: '/') */
15
  url?: string;
16
  /** Directory indexing behavior - true for auto-index, false to disable, string for specific index file */
17
  index?: boolean | string;
18
  /** Allow serving dot files (default: false) */
19
  dot?: boolean;
20
  /** Pass through to next handler on 404 instead of returning error (default: false) */
21
  passthrough?: boolean;
22
  /** Enable gzip compression (default: true) */
23
  gzip?: boolean;
24
  /** Enable CORS headers (default: false) */
25
  cors?: boolean;
26
  /** Add X-From-Cache header for cached responses (default: false) */
27
  cachedHeader?: boolean;
28
  /** Cache configuration object or false to disable caching */
29
  cache?: CacheOptions | false;
30
}
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
const st = require('st');
37

38
// Basic configuration
39
const basicHandler = st({
40
  path: './public',
41
  url: '/static'
42
});
43

44
// Security-focused configuration
45
const secureHandler = st({
46
  path: './secure',
47
  dot: false,        // Block dot files
48
  passthrough: true, // Let app handle 404s
49
  cors: false        // No cross-origin access
50
});
51

52
// Performance-optimized configuration
53
const fastHandler = st({
54
  path: './assets',
55
  gzip: true,
56
  cachedHeader: true,
57
  cache: {
58
    content: {
59
      maxSize: 1024 * 1024 * 128, // 128MB cache
60
      maxAge: 1000 * 60 * 30       // 30 minute cache
61
    }
62
  }
63
});
64
```
65

66
### Path Configuration
67

68
Filesystem path configuration and behavior.
69

70
```javascript { .api }
71
/**
72
 * Required filesystem path to serve files from
73
 * - Must be a string
74
 * - Will be resolved to absolute path
75
 * - Must exist and be accessible
76
 */
77
path: string;
78
```
79

80
**Usage Example:**
81

82
```javascript
83
// Relative path (resolved against process.cwd())
84
const handler1 = st({ path: './static' });
85

86
// Absolute path
87
const handler2 = st({ path: '/var/www/html' });
88

89
// Using path module for cross-platform compatibility
90
const path = require('path');
91
const handler3 = st({ 
92
  path: path.join(__dirname, 'public') 
93
});
94
```
95

96
### URL Mount Point
97

98
URL mounting configuration for serving files at specific paths.
99

100
```javascript { .api }
101
/**
102
 * URL mount point where files will be served
103
 * - Default: '/'
104
 * - Must start with '/'
105
 * - Example: '/static' serves files at /static/file.js
106
 */
107
url?: string;
108
```
109

110
**Usage Example:**
111

112
```javascript
113
// Serve at root (default)
114
const rootHandler = st({ path: './public' });
115

116
// Serve at /static
117
const staticHandler = st({ 
118
  path: './assets', 
119
  url: '/static' 
120
});
121

122
// Serve at nested path
123
const nestedHandler = st({ 
124
  path: './images', 
125
  url: '/assets/images' 
126
});
127
```
128

129
### Directory Indexing
130

131
Configuration for directory listing and index file behavior.
132

133
```javascript { .api }
134
/**
135
 * Directory indexing behavior
136
 * - true: Enable auto-indexing (generates HTML directory listings)
137
 * - false: Return 404 for directory requests
138
 * - string: Use specific file as index (e.g., 'index.html')
139
 */
140
index?: boolean | string;
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// Auto-indexing enabled (shows directory listings)
147
const autoIndexHandler = st({
148
  path: './files',
149
  index: true
150
});
151

152
// Use specific index file
153
const htmlIndexHandler = st({
154
  path: './website',
155
  index: 'index.html'
156
});
157

158
// Disable directory access entirely
159
const noIndexHandler = st({
160
  path: './api-only',
161
  index: false
162
});
163
```
164

165
### Security Options
166

167
Security-related configuration options.
168

169
```javascript { .api }
170
/**
171
 * Dot file access control
172
 * - false: Return 403 for any URL with dot-file part (default)
173
 * - true: Allow dot-files to be served normally
174
 */
175
dot?: boolean;
176

177
/**
178
 * Passthrough behavior for unhandled requests
179
 * - false: Return 404 when file not found (default)
180
 * - true: Call next() or return false for middleware chains
181
 */
182
passthrough?: boolean;
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
// Secure configuration - block dot files
189
const secureHandler = st({
190
  path: './public',
191
  dot: false  // Blocks .htaccess, .env, etc.
192
});
193

194
// Development configuration - allow dot files
195
const devHandler = st({
196
  path: './dev-files',
197
  dot: true  // Allows .well-known, etc.
198
});
199

200
// Middleware-friendly configuration
201
const middlewareHandler = st({
202
  path: './assets',
203
  passthrough: true  // Falls through to next handler
204
});
205

206
// Use with Express-style middleware
207
app.use((req, res, next) => {
208
  middlewareHandler(req, res, next);
209
});
210
```
211

212
### Performance Options
213

214
Performance and compression configuration.
215

216
```javascript { .api }
217
/**
218
 * Gzip compression
219
 * - true: Enable gzip compression for supported files (default)
220
 * - false: Disable compression entirely
221
 */
222
gzip?: boolean;
223

224
/**
225
 * CORS headers
226
 * - false: No CORS headers (default)
227
 * - true: Add permissive CORS headers for cross-origin access
228
 */
229
cors?: boolean;
230

231
/**
232
 * Cache debugging
233
 * - false: No cache headers (default)
234
 * - true: Add X-From-Cache header when serving from cache
235
 */
236
cachedHeader?: boolean;
237
```
238

239
**Usage Examples:**
240

241
```javascript
242
// High-performance configuration
243
const fastHandler = st({
244
  path: './assets',
245
  gzip: true,          // Compress responses
246
  cachedHeader: true   // Debug cache hits
247
});
248

249
// API-friendly configuration
250
const apiHandler = st({
251
  path: './api-docs',
252
  cors: true,          // Allow cross-origin requests
253
  gzip: true
254
});
255

256
// No-compression configuration (for pre-compressed files)
257
const preCompressedHandler = st({
258
  path: './compressed-assets',
259
  gzip: false  // Files are already compressed
260
});
261
```
262

263
### Cache Configuration
264

265
Multi-level caching system configuration.
266

267
```javascript { .api }
268
/**
269
 * Cache configuration object or false to disable all caching
270
 */
271
cache?: CacheOptions | false;
272

273
interface CacheOptions {
274
  /** File descriptor cache settings */
275
  fd?: CacheConfig;
276
  /** File stat cache settings */
277
  stat?: CacheConfig;
278
  /** File content cache settings */
279
  content?: ContentCacheConfig;
280
  /** Directory index HTML cache settings */
281
  index?: CacheConfig;
282
  /** Directory listing cache settings */
283
  readdir?: CacheConfig;
284
}
285

286
interface CacheConfig {
287
  /** Maximum number of items to cache */
288
  max?: number;
289
  /** Maximum age in milliseconds */
290
  maxAge?: number;
291
  /** Whether to ignore fetch abortion (default: true) */
292
  ignoreFetchAbort?: boolean;
293
}
294

295
interface ContentCacheConfig extends CacheConfig {
296
  /** Maximum memory size in bytes for content cache */
297
  maxSize?: number;
298
  /** Function to calculate item size (default: item.length) */
299
  sizeCalculation?: (item: any) => number;
300
  /** Custom Cache-Control header value */
301
  cacheControl?: string;
302
}
303
```
304

305
**Default Cache Settings:**
306

307
```javascript
308
// Default cache configuration
309
const defaultCache = {
310
  fd: {
311
    max: 1000,
312
    maxAge: 1000 * 60 * 60,  // 1 hour
313
    ignoreFetchAbort: true
314
  },
315
  stat: {
316
    max: 5000,
317
    maxAge: 1000 * 60,       // 1 minute
318
    ignoreFetchAbort: true
319
  },
320
  content: {
321
    maxSize: 1024 * 1024 * 64,  // 64MB
322
    maxAge: 1000 * 60 * 10,     // 10 minutes
323
    ignoreFetchAbort: true
324
  },
325
  index: {
326
    maxSize: 1024 * 8,       // 8KB
327
    maxAge: 1000 * 60 * 10,  // 10 minutes
328
    ignoreFetchAbort: true
329
  },
330
  readdir: {
331
    maxSize: 1000,
332
    maxAge: 1000 * 60 * 10,  // 10 minutes
333
    ignoreFetchAbort: true
334
  }
335
};
336
```
337

338
**Usage Examples:**
339

340
```javascript
341
// Disable all caching
342
const noCacheHandler = st({
343
  path: './dynamic',
344
  cache: false
345
});
346

347
// Custom cache configuration
348
const customCacheHandler = st({
349
  path: './static',
350
  cache: {
351
    content: {
352
      maxSize: 1024 * 1024 * 256,  // 256MB cache
353
      maxAge: 1000 * 60 * 60,      // 1 hour
354
      cacheControl: 'public, max-age=3600'
355
    },
356
    stat: {
357
      maxAge: 1000 * 30  // 30 second stat cache
358
    }
359
  }
360
});
361

362
// Memory-conscious configuration
363
const lightCacheHandler = st({
364
  path: './files',
365
  cache: {
366
    content: {
367
      maxSize: 1024 * 1024 * 16,  // 16MB only
368
      maxAge: 1000 * 60 * 5       // 5 minute cache
369
    },
370
    fd: {
371
      max: 100  // Fewer file descriptors
372
    }
373
  }
374
});
375

376
// Development configuration with short cache times
377
const devCacheHandler = st({
378
  path: './dev',
379
  cache: {
380
    content: {
381
      maxAge: 1000 * 10,  // 10 second cache
382
      cacheControl: 'no-cache'
383
    },
384
    stat: {
385
      maxAge: 1000 * 5   // 5 second stat cache
386
    }
387
  }
388
});
389
```
390

391
### Cache Control Headers
392

393
Automatic cache control header management based on content cache configuration.
394

395
```javascript { .api }
396
/**
397
 * Cache-Control header behavior:
398
 * - If content.maxAge is false: No Cache-Control header set
399
 * - If content.cacheControl is string: Use that exact value
400
 * - If cache is false: 'no-cache'
401
 * - Default: 'public, max-age=' + (content.maxAge / 1000)
402
 */
403
```
404

405
**Usage Examples:**
406

407
```javascript
408
// Explicit cache control
409
const explicitHandler = st({
410
  path: './assets',
411
  cache: {
412
    content: {
413
      maxAge: 1000 * 60 * 60,  // 1 hour
414
      cacheControl: 'public, max-age=3600, immutable'
415
    }
416
  }
417
});
418

419
// No cache headers
420
const noCacheHeaderHandler = st({
421
  path: './dynamic',
422
  cache: {
423
    content: {
424
      maxAge: false  // No Cache-Control header
425
    }
426
  }
427
});
428

429
// Private cache
430
const privateHandler = st({
431
  path: './user-files',
432
  cache: {
433
    content: {
434
      maxAge: 1000 * 60 * 10,  // 10 minutes
435
      cacheControl: 'private, max-age=600'
436
    }
437
  }
438
});
439
```