0
# Nodemon
1

2
Nodemon is a development tool that automatically monitors Node.js applications and restarts them when file changes are detected in the directory. It serves as a drop-in replacement wrapper for the `node` command, requiring no changes to existing code or development workflows.
3

4
## Package Information
5

6
- **Package Name**: nodemon
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -g nodemon` or `npm install --save-dev nodemon`
10

11
## Core Imports
12

13
For programmatic usage (as a library):
14

15
```javascript
16
const nodemon = require('nodemon');
17
```
18

19
For CommonJS with destructuring:
20

21
```javascript
22
const { config } = require('nodemon');
23
```
24

25
For TypeScript (using CommonJS export pattern):
26

27
```typescript
28
import nodemon = require('nodemon');
29
import type { NodemonSettings, NodemonConfig } from 'nodemon';
30

31
// Alternative ES module style (requires esModuleInterop)
32
import nodemon from 'nodemon';
33
import type { NodemonSettings, NodemonConfig } from 'nodemon';
34
```
35

36
## Basic Usage
37

38
### CLI Usage
39

40
```bash
41
# Basic usage - monitors current directory and restarts on file changes
42
nodemon app.js
43

44
# With specific extensions
45
nodemon --ext js,json,ts app.js
46

47
# With custom watch directories
48
nodemon --watch src --watch config app.js
49

50
# With ignore patterns
51
nodemon --ignore test/ --ignore logs/ app.js
52
```
53

54
### Programmatic Usage
55

56
```javascript
57
const nodemon = require('nodemon');
58

59
// Object configuration
60
nodemon({
61
  script: 'app.js',
62
  ext: 'js json ts',
63
  watch: ['src/', 'config/'],
64
  ignore: ['test/', 'logs/']
65
});
66

67
// String configuration (CLI-style)
68
nodemon('--ext js,json app.js');
69

70
// Event handling
71
nodemon.on('start', function () {
72
  console.log('App has started');
73
}).on('quit', function () {
74
  console.log('App has quit');
75
  process.exit();
76
}).on('restart', function (files) {
77
  console.log('App restarted due to: ', files);
78
});
79
```
80

81
## Architecture
82

83
Nodemon is built around several key components:
84

85
- **Main Function**: The primary `nodemon()` function that can accept configuration objects or CLI-style strings
86
- **Event System**: Built-in event emitter for monitoring application lifecycle (start, restart, quit, crash)
87
- **File Monitoring**: Uses Chokidar for efficient file system watching with ignore patterns and custom rules
88
- **Process Management**: Handles child process spawning, restarting, and signal forwarding
89
- **Configuration System**: Supports JSON config files, CLI arguments, and programmatic options
90
- **CLI Interface**: Command-line tool with comprehensive argument parsing and help system
91

92
## Capabilities
93

94
### Core API
95

96
The main nodemon function and essential control methods for starting, restarting, and managing monitored processes.
97

98
```javascript { .api }
99
/**
100
 * Main nodemon function - starts monitoring with given settings
101
 * @param settings - Configuration object or CLI-style string
102
 * @returns Nodemon instance for chaining
103
 */
104
function nodemon(settings: NodemonSettings | string): Nodemon;
105

106
interface Nodemon {
107
  /** Manually restart the monitored process */
108
  restart(): Nodemon;
109
  
110
  /** Reset nodemon to clean state (useful for testing) */
111
  reset(callback?: Function): Nodemon;
112
  
113
  /** Reference to internal configuration */
114
  config: NodemonSettings;
115
  
116
  /** Dynamic stdout stream (available when stdout: false is configured) */
117
  stdout?: NodeJS.ReadableStream;
118
  
119
  /** Dynamic stderr stream (available when stdout: false is configured) */
120
  stderr?: NodeJS.ReadableStream;
121
}
122
```
123

124
[Core API](./core-api.md)
125

126
### Event System
127

128
Event emitter interface for monitoring application lifecycle and handling custom events.
129

130
```javascript { .api }
131
interface NodemonEventListener {
132
  /** Add event listener for nodemon events */
133
  on(event: 'start' | 'crash' | 'readable', listener: () => void): Nodemon;
134
  on(event: 'log', listener: (e: NodemonEventLog) => void): Nodemon;
135
  on(event: 'stdout' | 'stderr', listener: (e: string) => void): Nodemon;
136
  on(event: 'restart', listener: (e?: NodemonEventRestart) => void): Nodemon;
137
  on(event: 'quit', listener: (e?: NodemonEventQuit) => void): Nodemon;
138
  on(event: 'exit', listener: (e?: number) => void): Nodemon;
139
  on(event: 'config:update', listener: (e?: NodemonEventConfig) => void): Nodemon;
140
}
141

142
type NodemonEventHandler = 'start' | 'crash' | 'exit' | 'quit' | 'restart' | 'config:update' | 'log' | 'readable' | 'stdout' | 'stderr';
143
```
144

145
[Event System](./events.md)
146

147
### Configuration
148

149
Comprehensive configuration options for file watching, process execution, and monitoring behavior.
150

151
```javascript { .api }
152
interface NodemonSettings extends NodemonConfig, NodemonExecOptions {
153
  events?: Record<string, string>;
154
  env?: Record<string, string>;
155
}
156

157
interface NodemonConfig {
158
  restartable?: false | string;
159
  colours?: boolean;
160
  watch?: string[];
161
  ignore?: string[];
162
  ext?: string;
163
  verbose?: boolean;
164
  stdout?: boolean;
165
  delay?: number;
166
  // ... additional configuration options
167
}
168
```
169

170
[Configuration](./configuration.md)
171

172
## Types
173

174
### Event Types
175

176
```javascript { .api }
177
type NodemonEventHandler = 
178
  | 'start' 
179
  | 'crash' 
180
  | 'exit' 
181
  | 'quit' 
182
  | 'restart' 
183
  | 'config:update' 
184
  | 'log' 
185
  | 'readable' 
186
  | 'stdout' 
187
  | 'stderr';
188

189
interface NodemonEventLog {
190
  /** Log level: detail, log, status, error, fail */
191
  type: 'detail' | 'log' | 'status' | 'error' | 'fail';
192
  /** Plain text message */
193
  message: string;
194
  /** Terminal escape codes with color and "[nodemon]" prefix */
195
  colour: string;
196
}
197

198
interface NodemonEventRestart {
199
  matched?: {
200
    result: string[];
201
    total: number;
202
  };
203
}
204

205
type NodemonEventQuit = 143 | 130;
206
```
207

208
### Configuration Types
209

210
```javascript { .api }
211
interface NodemonExecOptions {
212
  script: string;
213
  scriptPosition?: number;
214
  args?: string[];
215
  ext?: string;
216
  exec?: string;
217
  execArgs?: string[];
218
  nodeArgs?: string[];
219
}
220

221
interface NodemonEventConfig {
222
  run: boolean;
223
  system: {
224
    cwd: string;
225
  };
226
  required: boolean;
227
  dirs: string[];
228
  timeout: number;
229
  options: NodemonConfig;
230
  lastStarted: number;
231
  loaded: string[];
232
  load: (settings: NodemonSettings, ready: (config: NodemonEventConfig) => void) => void;
233
  reset: () => void;
234
}
235
```