npm-express

1
# Application Management
2

3
Core Express application creation, configuration, and server management functionality for setting up web applications and APIs.
4

5
## Capabilities
6

7
### Application Factory
8

9
Creates a new Express application instance with routing and middleware capabilities.
10

11
```javascript { .api }
12
/**
13
 * Creates an Express application instance
14
 * @returns {Application} Express application instance with routing and middleware
15
 */
16
function express(): Application;
17
```
18

19
**Usage Example:**
20

21
```javascript
22
const express = require('express');
23
const app = express();
24

25
// App is now ready for configuration and routing
26
app.get('/', (req, res) => {
27
  res.send('Hello World!');
28
});
29
```
30

31
### Application Settings
32

33
Configure application behavior through settings that control Express features.
34

35
```javascript { .api }
36
/**
37
 * Set application setting to a value
38
 * @param {string} setting - Setting name
39
 * @param {any} value - Setting value
40
 * @returns {Application} Application instance for chaining
41
 */
42
app.set(setting: string, value: any): Application;
43

44
/**
45
 * Get application setting value
46
 * @param {string} setting - Setting name
47
 * @returns {any} Setting value
48
 */
49
app.get(setting: string): any;
50

51
/**
52
 * Enable a boolean setting
53
 * @param {string} setting - Setting name
54
 * @returns {Application} Application instance for chaining
55
 */
56
app.enable(setting: string): Application;
57

58
/**
59
 * Disable a boolean setting
60
 * @param {string} setting - Setting name
61
 * @returns {Application} Application instance for chaining
62
 */
63
app.disable(setting: string): Application;
64

65
/**
66
 * Check if a boolean setting is enabled
67
 * @param {string} setting - Setting name
68
 * @returns {boolean} True if enabled, false otherwise
69
 */
70
app.enabled(setting: string): boolean;
71

72
/**
73
 * Check if a boolean setting is disabled
74
 * @param {string} setting - Setting name
75
 * @returns {boolean} True if disabled, false otherwise
76
 */
77
app.disabled(setting: string): boolean;
78
```
79

80
**Common Settings:**
81

82
- `case sensitive routing` - Enable case-sensitive routes (default: false)
83
- `env` - Environment mode (default: process.env.NODE_ENV || 'development')
84
- `etag` - ETag generation setting (default: 'weak')
85
- `jsonp callback name` - JSONP callback parameter name (default: 'callback')
86
- `query parser` - Query string parser setting (default: 'extended')
87
- `strict routing` - Enable strict routing (default: false)
88
- `subdomain offset` - Subdomain offset for parsing (default: 2)
89
- `trust proxy` - Proxy trust configuration (default: false)
90
- `view cache` - Template cache setting (default: true in production)
91
- `view engine` - Default template engine
92
- `views` - Views directory path (default: './views')
93
- `x-powered-by` - X-Powered-By header setting (default: true)
94

95
**Usage Examples:**
96

97
```javascript
98
const app = express();
99

100
// Configure settings
101
app.set('view engine', 'ejs');
102
app.set('views', './templates');
103
app.set('port', process.env.PORT || 3000);
104

105
// Enable/disable features
106
app.enable('trust proxy');
107
app.disable('x-powered-by');
108

109
// Check settings
110
if (app.enabled('trust proxy')) {
111
  console.log('Proxy trust is enabled');
112
}
113

114
const port = app.get('port');
115
console.log(`Server will run on port ${port}`);
116
```
117

118
### Application Path
119

120
Get the canonical path of the application when mounted as a sub-application.
121

122
```javascript { .api }
123
/**
124
 * Returns the canonical path of the application
125
 * @returns {string} The path where the app is mounted, empty string for main app
126
 */
127
app.path(): string;
128
```
129

130
**Usage Example:**
131

132
```javascript
133
const express = require('express');
134
const app = express();
135
const admin = express();
136

137
// Mount admin as sub-application
138
app.use('/admin', admin);
139

140
console.log(app.path());    // '' (empty string for main app)  
141
console.log(admin.path());  // '/admin'
142

143
// With nested mounting
144
const users = express();
145
admin.use('/users', users);
146
console.log(users.path());  // '/admin/users'
147
```
148

149
### Server Startup
150

151
Start HTTP server to listen for incoming connections.
152

153
```javascript { .api }
154
/**
155
 * Start HTTP server listening on specified port and hostname
156
 * @param {number} [port] - Port number (default: 0 for random port)
157
 * @param {string} [hostname] - Hostname (default: undefined, listens on all interfaces)
158
 * @param {Function} [callback] - Callback function called when server starts
159
 * @returns {http.Server} Node.js HTTP server instance
160
 */
161
app.listen(port?: number, hostname?: string, callback?: () => void): http.Server;
162

163
/**
164
 * Start HTTP server listening on specified port
165
 * @param {number} [port] - Port number
166
 * @param {Function} [callback] - Callback function
167
 * @returns {http.Server} Node.js HTTP server instance
168
 */
169
app.listen(port?: number, callback?: () => void): http.Server;
170

171
/**
172
 * Start HTTP server with callback only
173
 * @param {Function} [callback] - Callback function
174
 * @returns {http.Server} Node.js HTTP server instance
175
 */
176
app.listen(callback?: () => void): http.Server;
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
const app = express();
183

184
// Basic server startup
185
app.listen(3000, () => {
186
  console.log('Server running on port 3000');
187
});
188

189
// Specify hostname
190
app.listen(3000, 'localhost', () => {
191
  console.log('Server running on localhost:3000');
192
});
193

194
// Use environment port
195
const port = process.env.PORT || 3000;
196
app.listen(port, () => {
197
  console.log(`Server running on port ${port}`);
198
});
199

200
// Get server instance for further configuration
201
const server = app.listen(3000);
202
server.on('error', (err) => {
203
  console.error('Server error:', err);
204
});
205
```
206

207
### Template Engine Integration
208

209
Register and configure template engines for rendering dynamic content.
210

211
```javascript { .api }
212
/**
213
 * Register template engine for specific file extension
214
 * @param {string} ext - File extension (without dot)
215
 * @param {Function} callback - Template engine function
216
 * @returns {Application} Application instance for chaining
217
 */
218
app.engine(ext: string, callback: TemplateEngine): Application;
219

220
/**
221
 * Render view template with optional locals
222
 * @param {string} view - View name/path
223
 * @param {Object} [options] - Template locals and options
224
 * @param {Function} [callback] - Callback function with rendered HTML
225
 */
226
app.render(view: string, options?: any, callback?: (err: Error | null, html?: string) => void): void;
227

228
/**
229
 * Template engine function signature
230
 */
231
type TemplateEngine = (filePath: string, options: any, callback: (err: Error | null, rendered?: string) => void) => void;
232
```
233

234
**Usage Examples:**
235

236
```javascript
237
const app = express();
238

239
// Set view engine
240
app.set('view engine', 'ejs');
241
app.set('views', './views');
242

243
// Custom template engine
244
app.engine('ntl', (filePath, options, callback) => {
245
  // Custom template processing
246
  fs.readFile(filePath, (err, content) => {
247
    if (err) return callback(err);
248
    
249
    const rendered = content.toString()
250
      .replace(/\{\{(.+?)\}\}/g, (match, key) => options[key] || '');
251
    
252
    callback(null, rendered);
253
  });
254
});
255

256
// Render template programmatically
257
app.render('index', { title: 'My App' }, (err, html) => {
258
  if (err) {
259
    console.error('Render error:', err);
260
  } else {
261
    console.log('Rendered HTML:', html);
262
  }
263
});
264
```
265

266
## Application Instance Properties
267

268
```javascript { .api }
269
/**
270
 * Express application instance interface
271
 */
272
interface Application {
273
  /** Application locals available to all templates */
274
  locals: { [key: string]: any };
275
  /** Application settings */
276
  settings: { [key: string]: any };
277
  /** Application mount path when used as sub-app */
278
  mountpath: string | string[];
279
}
280
```
281

282
**Usage Examples:**
283

284
```javascript
285
const app = express();
286

287
// Set application locals
288
app.locals.title = 'My Express App';
289
app.locals.email = 'admin@example.com';
290

291
// Access in templates (EJS example)
292
// <h1><%= title %></h1>
293
// <p>Contact: <%= email %></p>
294

295
// Check mount path (useful for sub-applications)
296
console.log(app.mountpath); // '/' for main app
297
```