0
# Event System
1

2
Nodemon provides a comprehensive event system for monitoring application lifecycle and handling custom events. All event methods support method chaining and follow the Node.js EventEmitter pattern.
3

4
## Capabilities
5

6
### Event Listener Methods
7

8
#### On Method
9

10
Adds an event listener for the specified event.
11

12
```javascript { .api }
13
/**
14
 * Add event listener for nodemon events
15
 * @param event - Event name to listen for
16
 * @param listener - Event handler function
17
 * @returns Nodemon instance for chaining
18
 */
19
on(event: 'start' | 'crash' | 'readable', listener: () => void): Nodemon;
20
on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon;
21
on(event: 'stdout' | 'stderr', listener: (e: string) => void): Nodemon;
22
on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon;
23
on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon;
24
on(event: 'exit', listener: (e?: number) => void): Nodemon;
25
on(event: 'config:update', listener: (e?: NodemonEventConfig) => void): Nodemon;
26
```
27

28
#### AddListener Method
29

30
Alias for the `on` method, provides the same functionality.
31

32
```javascript { .api }
33
/**
34
 * Add event listener (alias for 'on' method)
35
 * @param event - Event name to listen for
36
 * @param listener - Event handler function
37
 * @returns Nodemon instance for chaining
38
 */
39
addListener(event: NodemonEventHandler, listener: Function): Nodemon;
40
```
41

42
#### Once Method
43

44
Adds a one-time event listener that is automatically removed after the first event.
45

46
```javascript { .api }
47
/**
48
 * Add one-time event listener
49
 * @param event - Event name to listen for
50
 * @param listener - Event handler function
51
 * @returns Nodemon instance for chaining
52
 */
53
once(event: NodemonEventHandler, listener: Function): Nodemon;
54
```
55

56
### Event Control Methods
57

58
#### Emit Method
59

60
Emits an event to all registered listeners.
61

62
```javascript { .api }
63
/**
64
 * Emit an event to all listeners
65
 * @param type - Event type to emit
66
 * @param event - Optional event data
67
 * @returns Nodemon instance for chaining
68
 */
69
emit(type: NodemonEventHandler, event?: any): Nodemon;
70
```
71

72
#### RemoveAllListeners Method
73

74
Removes all event listeners for the specified event, or all events if no event is specified.
75

76
```javascript { .api }
77
/**
78
 * Remove all event listeners for specified event
79
 * @param event - Optional specific event to remove listeners for
80
 * @returns Nodemon instance for chaining
81
 */
82
removeAllListeners(event?: NodemonEventHandler): Nodemon;
83
```
84

85
## Event Types
86

87
### Lifecycle Events
88

89
#### Start Event
90

91
Emitted when the child process has started.
92

93
```javascript
94
nodemon.on('start', function () {
95
  console.log('App has started');
96
});
97
```
98

99
#### Restart Event
100

101
Emitted when the child process has restarted, optionally includes information about files that triggered the restart.
102

103
```javascript
104
nodemon.on('restart', function (files) {
105
  if (files) {
106
    console.log('App restarted due to:', files);
107
  } else {
108
    console.log('App restarted manually');
109
  }
110
});
111
```
112

113
#### Exit Event
114

115
Emitted when the child process has cleanly exited (no crash).
116

117
```javascript
118
nodemon.on('exit', function (code) {
119
  console.log('App exited with code:', code);
120
});
121
```
122

123
#### Crash Event
124

125
Emitted when the child process has crashed (nodemon will not emit exit for crashes).
126

127
```javascript
128
nodemon.on('crash', function () {
129
  console.log('App crashed');
130
});
131
```
132

133
#### Quit Event
134

135
Emitted when nodemon itself quits.
136

137
```javascript
138
nodemon.on('quit', function (code) {
139
  console.log('Nodemon quit with code:', code);
140
  process.exit();
141
});
142
```
143

144
### Configuration Events
145

146
#### Config Update Event
147

148
Emitted when nodemon's configuration has changed.
149

150
```javascript
151
nodemon.on('config:update', function (config) {
152
  console.log('Configuration updated');
153
  console.log('Watching:', config.options.watch);
154
});
155
```
156

157
### Output Events
158

159
#### Log Event
160

161
Emitted for nodemon's own log messages (when verbose mode is enabled).
162

163
```javascript
164
nodemon.on('log', function (event) {
165
  console.log(`[${event.type}] ${event.message}`);
166
});
167
```
168

169
#### Stdout Event
170

171
Emitted for stdout stream from the child process.
172

173
```javascript
174
nodemon.on('stdout', function (data) {
175
  console.log('Child stdout:', data);
176
});
177
```
178

179
#### Stderr Event
180

181
Emitted for stderr stream from the child process.
182

183
```javascript
184
nodemon.on('stderr', function (data) {
185
  console.error('Child stderr:', data);
186
});
187
```
188

189
#### Readable Event
190

191
Emitted when stdout and stderr streams are ready for reading.
192

193
```javascript
194
nodemon.on('readable', function () {
195
  console.log('Streams are ready');
196
});
197
```
198

199
## Event Data Types
200

201
```javascript { .api }
202
type NodemonEventHandler = 
203
  | 'start' 
204
  | 'crash' 
205
  | 'exit' 
206
  | 'quit' 
207
  | 'restart' 
208
  | 'config:update' 
209
  | 'log' 
210
  | 'readable' 
211
  | 'stdout' 
212
  | 'stderr';
213

214
interface NodemonEventLog {
215
  /** Log level: detail (verbose), log (normal), status (process state), error (nodemon error), fail (subprocess crash) */
216
  type: 'detail' | 'log' | 'status' | 'error' | 'fail';
217
  /** Plain text message without formatting */
218
  message: string;
219
  /** Message with terminal escape codes and "[nodemon]" prefix for colored output */
220
  colour: string;
221
}
222

223
interface NodemonEventRestart {
224
  /** Information about files that triggered the restart */
225
  matched?: {
226
    /** Array of file paths that matched watch patterns */
227
    result: string[];
228
    /** Total number of matching files */
229
    total: number;
230
  };
231
}
232

233
/** Exit codes for quit event: 143 (SIGTERM), 130 (SIGINT/Ctrl+C) */
234
type NodemonEventQuit = 143 | 130;
235

236
interface NodemonEventListener {
237
  on(event: 'start' | 'crash' | 'readable', listener: () => void): Nodemon;
238
  on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon;
239
  on(event: 'stdout' | 'stderr', listener: (e: string) => void): Nodemon;
240
  on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon;
241
  on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon;
242
  on(event: 'exit', listener: (e?: number) => void): Nodemon;
243
  on(event: 'config:update', listener: (e?: NodemonEventConfig) => void): Nodemon;
244
}
245
```
246

247
## Usage Examples
248

249
### Basic Event Handling
250

251
```javascript
252
const nodemon = require('nodemon');
253

254
nodemon({
255
  script: 'app.js',
256
  ext: 'js json'
257
})
258
.on('start', function () {
259
  console.log('App has started');
260
})
261
.on('quit', function () {
262
  console.log('App has quit');
263
  process.exit();
264
})
265
.on('restart', function (files) {
266
  console.log('App restarted due to: ', files);
267
});
268
```
269

270
### Advanced Event Handling
271

272
```javascript
273
const nodemon = require('nodemon');
274

275
nodemon({ script: 'server.js', verbose: true });
276

277
// Handle all lifecycle events
278
nodemon
279
  .on('start', () => console.log('🚀 Server started'))
280
  .on('restart', (files) => {
281
    if (files) {
282
      console.log('🔄 Restarted due to changes in:', files.matched?.result);
283
    }
284
  })
285
  .on('crash', () => console.log('💥 Server crashed'))
286
  .on('exit', (code) => console.log(`✅ Server exited cleanly (${code})`))
287
  .on('quit', () => process.exit());
288

289
// Handle output streams
290
nodemon
291
  .on('stdout', (data) => console.log('OUT:', data))
292
  .on('stderr', (data) => console.error('ERR:', data));
293

294
// Handle verbose logging
295
nodemon.on('log', (event) => {
296
  if (event.type === 'error') {
297
    console.error('Nodemon error:', event.message);
298
  }
299
});
300

301
// Manual control
302
setTimeout(() => {
303
  console.log('Triggering manual restart...');
304
  nodemon.emit('restart');
305
}, 10000);
306
```
307

308
### Event Cleanup
309

310
```javascript
311
const nodemon = require('nodemon');
312

313
// Start monitoring
314
nodemon({ script: 'app.js' });
315

316
// Add listeners
317
nodemon.on('start', startHandler);
318
nodemon.on('restart', restartHandler);
319

320
// Clean up specific event
321
nodemon.removeAllListeners('start');
322

323
// Clean up all events
324
nodemon.removeAllListeners();
325

326
function startHandler() {
327
  console.log('Started');
328
}
329

330
function restartHandler(files) {
331
  console.log('Restarted:', files);
332
}
333
```
334

335
## Notes
336

337
- All event methods return the nodemon instance for method chaining
338
- Events follow the Node.js EventEmitter pattern
339
- The `readable` event is useful for custom stream processing
340
- Log events are only emitted when verbose mode is enabled
341
- Restart events may not include file information for manual restarts
342
- Multiple listeners can be attached to the same event
343
- Event listeners persist until explicitly removed or nodemon is reset