0
# Core API
1
2
The core nodemon API provides the main function and essential control methods for starting, restarting, and managing monitored processes.
3
4
## Capabilities
5
6
### Main Function
7
8
The primary nodemon function that starts monitoring with given settings.
9
10
```javascript { .api }
11
/**
12
* Main nodemon function - starts monitoring with given settings
13
* @param settings - Configuration object or CLI-style string
14
* @returns Nodemon instance for chaining
15
*/
16
function nodemon(settings: NodemonSettings | string): Nodemon;
17
```
18
19
**String Parameter Processing**: When a string is provided, nodemon automatically processes it as CLI arguments. The string is normalized by adding "node" and "nodemon" prefixes if not present, then parsed as command-line arguments. For example, `nodemon("app.js")` becomes equivalent to running `node nodemon app.js`.
20
21
**Usage Examples:**
22
23
```javascript
24
const nodemon = require('nodemon');
25
26
// Object configuration
27
nodemon({
28
script: 'app.js',
29
ext: 'js json',
30
watch: ['src/'],
31
ignore: ['test/']
32
});
33
34
// String configuration (CLI-style)
35
nodemon('--ext js,json --watch src/ app.js');
36
37
// Minimal configuration
38
nodemon({ script: 'server.js' });
39
```
40
41
### Restart Method
42
43
Manually triggers a restart of the monitored process.
44
45
```javascript { .api }
46
/**
47
* Manually restart the monitored process
48
* @returns Nodemon instance for chaining
49
*/
50
restart(): Nodemon;
51
```
52
53
**Usage Examples:**
54
55
```javascript
56
const nodemon = require('nodemon');
57
58
// Start monitoring
59
nodemon({ script: 'app.js' });
60
61
// Trigger manual restart
62
nodemon.restart();
63
64
// Chaining example
65
nodemon({ script: 'app.js' })
66
.on('start', () => console.log('Started'))
67
.restart();
68
```
69
70
### Reset Method
71
72
Resets nodemon to clean state, removing all event listeners and stopping monitoring.
73
74
```javascript { .api }
75
/**
76
* Reset nodemon to clean state (useful for testing)
77
* @param callback - Optional callback executed when reset is complete
78
* @returns Nodemon instance for chaining
79
*/
80
reset(callback?: Function): Nodemon;
81
```
82
83
**Usage Examples:**
84
85
```javascript
86
const nodemon = require('nodemon');
87
88
// Reset with callback
89
nodemon.reset(() => {
90
console.log('Reset complete');
91
});
92
93
// Common testing pattern
94
afterEach((done) => {
95
nodemon.reset(done);
96
});
97
```
98
99
### Configuration Property
100
101
Reference to the internal configuration object used by nodemon.
102
103
```javascript { .api }
104
/**
105
* Reference to internal configuration
106
*/
107
config: NodemonSettings;
108
109
/** Dynamic stdout stream (available when stdout: false is configured) */
110
stdout?: NodeJS.ReadableStream;
111
112
/** Dynamic stderr stream (available when stdout: false is configured) */
113
stderr?: NodeJS.ReadableStream;
114
```
115
116
**Usage Examples:**
117
118
```javascript
119
const nodemon = require('nodemon');
120
121
// Start monitoring
122
nodemon({ script: 'app.js', watch: ['src/'] });
123
124
// Access configuration
125
console.log(nodemon.config.watch); // ['src/']
126
console.log(nodemon.config.script); // 'app.js'
127
console.log(nodemon.config.ext); // current extensions being watched
128
129
// Access dynamic streams (when stdout: false is configured)
130
nodemon({ script: 'app.js', stdout: false });
131
nodemon.on('start', () => {
132
if (nodemon.stdout) {
133
nodemon.stdout.pipe(process.stdout);
134
}
135
if (nodemon.stderr) {
136
nodemon.stderr.pipe(process.stderr);
137
}
138
});
139
```
140
141
## Core Types
142
143
```javascript { .api }
144
interface Nodemon {
145
/** Main function signature when called as function */
146
(settings: NodemonSettings): Nodemon;
147
148
/** Manually restart the monitored process */
149
restart(): Nodemon;
150
151
/** Reset nodemon to clean state */
152
reset(callback?: Function): Nodemon;
153
154
/** Remove all event listeners for specified event */
155
removeAllListeners(event?: NodemonEventHandler): Nodemon;
156
157
/** Emit an event to all listeners */
158
emit(type: NodemonEventHandler, event?: any): Nodemon;
159
160
/** Reference to internal configuration */
161
config: NodemonSettings;
162
163
/** Dynamic stdout stream (available when stdout: false is configured) */
164
stdout?: NodeJS.ReadableStream;
165
166
/** Dynamic stderr stream (available when stdout: false is configured) */
167
stderr?: NodeJS.ReadableStream;
168
169
/** Event listener methods (inherited from NodemonEventListener) */
170
on(event: NodemonEventHandler, listener: Function): Nodemon;
171
addListener(event: NodemonEventHandler, listener: Function): Nodemon;
172
once(event: NodemonEventHandler, listener: Function): Nodemon;
173
}
174
175
interface NodemonEventConfig {
176
/** Whether monitoring is currently active */
177
run: boolean;
178
179
/** System information */
180
system: {
181
cwd: string;
182
};
183
184
/** Whether nodemon is being used as a required module */
185
required: boolean;
186
187
/** Directories being monitored */
188
dirs: string[];
189
190
/** Restart timeout in milliseconds */
191
timeout: number;
192
193
/** Current configuration options */
194
options: NodemonConfig;
195
196
/** Timestamp when monitoring last started */
197
lastStarted: number;
198
199
/** Array of loaded configuration files */
200
loaded: string[];
201
202
/** Load configuration with callback */
203
load: (settings: NodemonSettings, ready: (config: NodemonEventConfig) => void) => void;
204
205
/** Reset configuration to defaults */
206
reset: () => void;
207
}
208
```
209
210
## Notes
211
212
- The main nodemon function returns itself, enabling method chaining
213
- When called with a string, nodemon parses it as CLI-style arguments
214
- When called with an object, it uses the object as direct configuration
215
- The `config` property provides read-only access to internal state
216
- All methods return the nodemon instance for fluent chaining
217
- Only one nodemon instance can be active per process due to static configuration