0
# st (Static File Server)
1

2
st is a comprehensive static file server module for Node.js applications that enables efficient serving of static files with advanced features including etags, intelligent caching, CORS support, and gzip compression. It offers both programmatic API for integration into existing HTTP servers and Express applications, as well as a command-line interface for standalone static file serving.
3

4
## Package Information
5

6
- **Package Name**: st
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install st`
10

11
## Core Imports
12

13
```javascript
14
const st = require('st');
15
```
16

17
For ES modules:
18

19
```javascript
20
import st from 'st';
21
```
22

23
Access to Mount class:
24

25
```javascript
26
const { Mount } = require('st');
27
// or
28
const st = require('st');
29
const Mount = st.Mount;
30
```
31

32
## Basic Usage
33

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

38
// Simple static file serving
39
http.createServer(
40
  st(process.cwd())
41
).listen(1337);
42

43
// With configuration options
44
const mount = st({
45
  path: './static',
46
  url: '/static',
47
  cache: true,
48
  gzip: true,
49
  cors: true
50
});
51

52
http.createServer((req, res) => {
53
  if (mount(req, res)) {
54
    return; // Request handled by st
55
  }
56
  res.end('Not a static file');
57
}).listen(1338);
58
```
59

60
## Architecture
61

62
st is built around several key components:
63

64
- **Factory Function**: `st()` creates configured request handler functions
65
- **Mount Class**: Internal class managing file serving, caching, and request processing
66
- **Multi-level Caching**: LRU caches for file descriptors, stats, content, indexes, and directory listings
67
- **Security Layer**: Path traversal prevention and dot-file access controls
68
- **Compression Engine**: Automatic gzip compression with content negotiation
69
- **CLI Server**: Standalone HTTP server with extensive configuration options
70

71
## Capabilities
72

73
### Core Server Function
74

75
The main st() factory function and Mount class provide the core static file serving functionality with multiple configuration options.
76

77
```javascript { .api }
78
function st(path: string): RequestHandler;
79
function st(path: string, url: string): RequestHandler;
80
function st(path: string, url: string, options: StOptions): RequestHandler;
81
function st(options: StOptions): RequestHandler;
82

83
interface RequestHandler {
84
  (req: http.IncomingMessage, res: http.ServerResponse, next?: Function): boolean;
85
  _this: Mount;
86
}
87
```
88

89
[Core Server Function](./core-server.md)
90

91
### Configuration Options
92

93
Comprehensive configuration system supporting caching, security, performance, and behavior customization.
94

95
```javascript { .api }
96
interface StOptions {
97
  path: string;
98
  url?: string;
99
  index?: boolean | string;
100
  dot?: boolean;
101
  passthrough?: boolean;
102
  gzip?: boolean;
103
  cors?: boolean;
104
  cachedHeader?: boolean;
105
  cache?: CacheOptions | false;
106
}
107

108
interface CacheOptions {
109
  fd?: CacheConfig;
110
  stat?: CacheConfig;
111
  content?: ContentCacheConfig;
112
  index?: CacheConfig;
113
  readdir?: CacheConfig;
114
}
115
```
116

117
[Configuration Options](./configuration.md)
118

119
### CLI Interface
120

121
Command-line interface for running st as a standalone HTTP server with extensive configuration options.
122

123
```bash { .api }
124
st [options]
125

126
# Common options:
127
# -p, --port PORT        Listen on PORT (default=1337)
128
# -d, --dir DIRECTORY    Serve the contents of DIRECTORY
129
# -u, --url /url         Serve at this mount url (default=/)
130
# --cors                 Enable CORS headers
131
# --no-cache             Disable all caching
132
```
133

134
[CLI Interface](./cli.md)
135

136
## Dependencies
137

138
st requires the following npm packages:
139

140
- `lru-cache` (^11.1.0) - LRU cache implementation for file descriptors, stats, and content
141
- `bl` (^6.1.0) - Buffer list for collecting streamed data  
142
- `fd` (^0.0.3) - File descriptor management
143
- `mime` (^3.0.0) - MIME type detection based on file extensions
144
- `negotiator` (^1.0.0) - HTTP content negotiation utilities
145
- `graceful-fs` (^4.2.3) - Optional drop-in replacement for fs module with better error handling
146

147
## Types
148

149
```javascript { .api }
150
// Module exports
151
module.exports = st;
152
module.exports.Mount = Mount;
153

154
class Mount {
155
  constructor(options: StOptions);
156
  serve(req: http.IncomingMessage, res: http.ServerResponse, next?: Function): boolean;
157
  getCacheOptions(options: StOptions): ProcessedCacheOptions;
158
  getUriPath(url: string): string | number | false;
159
  getPath(uriPath: string): string;
160
  getUrl(filePath: string): string | false;
161
  error(error: Error | number, res: http.ServerResponse): void;
162
  index(path: string, req: http.IncomingMessage, res: http.ServerResponse): void;
163
  autoindex(path: string, req: http.IncomingMessage, res: http.ServerResponse): void;
164
  file(path: string, fd: number, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse, end: Function): void;
165
  cachedFile(path: string, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse): void;
166
  streamFile(path: string, fd: number, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse, end: Function): void;
167
}
168

169
interface CacheConfig {
170
  max?: number;
171
  maxAge?: number;
172
  ignoreFetchAbort?: boolean;
173
}
174

175
interface ContentCacheConfig extends CacheConfig {
176
  maxSize?: number;
177
  sizeCalculation?: (item: any) => number;
178
  cacheControl?: string;
179
}
180
```