0
# Configuration
1

2
Nodemon provides comprehensive configuration options for file watching, process execution, and monitoring behavior. Configuration can be provided through objects, CLI-style strings, configuration files, or environment variables.
3

4
## Imports
5

6
```typescript
7
import type { WatchOptions } from 'chokidar';
8
```
9

10
**Note**: The `watchOptions` property uses Chokidar's `WatchOptions` interface directly. This provides advanced file system monitoring capabilities including ignore patterns, polling options, and platform-specific optimizations.
11

12
## Capabilities
13

14
### Settings Interface
15

16
The main configuration interface that combines all configuration options.
17

18
```javascript { .api }
19
/**
20
 * Complete configuration settings for nodemon
21
 */
22
interface NodemonSettings extends NodemonConfig, NodemonExecOptions {
23
  /** Event command mappings for custom event handling */
24
  events?: Record<string, string>;
25
  /** Environment variables to set for the child process */
26
  env?: Record<string, string>;
27
}
28
```
29

30
### Core Configuration
31

32
Basic monitoring and behavior configuration options.
33

34
```javascript { .api }
35
interface NodemonConfig {
36
  /** String to trigger manual restart (default: "rs"), or false to disable */
37
  restartable?: false | string;
38
  
39
  /** Enable colored output in logs (default: true) */
40
  colours?: boolean;
41
  
42
  /** Map file extensions to executables (default: {py: "python", rb: "ruby", ts: "ts-node"}) */
43
  execMap?: { [key: string]: string };
44
  
45
  /** Root-level directories to ignore during monitoring */
46
  ignoreRoot?: string[];
47
  
48
  /** Directories or files to watch for changes (default: ["*.*"]) */
49
  watch?: string[];
50
  
51
  /** Patterns to ignore during file watching */
52
  ignore?: string[];
53
  
54
  /** Enable stdin for manual commands (default: true) */
55
  stdin?: boolean;
56
  
57
  /** Only run on file changes, not initially (default: false) */
58
  runOnChangeOnly?: boolean;
59
  
60
  /** Enable verbose logging output (default: false) */
61
  verbose?: boolean;
62
  
63
  /** Signal to send to child process on restart (default: "SIGUSR2") */
64
  signal?: string;
65
  
66
  /** Show child process stdout (default: true) */
67
  stdout?: boolean;
68
  
69
  /** Chokidar watch options for advanced file system monitoring (default: {}) */
70
  watchOptions?: WatchOptions;
71
  
72
  /** Help topic to display */
73
  help?: string;
74
  
75
  /** Show version information */
76
  version?: boolean;
77
  
78
  /** Working directory for nodemon and child process */
79
  cwd?: string;
80
  
81
  /** Dump configuration and exit (for debugging) */
82
  dump?: boolean;
83
  
84
  /** Delay restart by specified milliseconds */
85
  delay?: number;
86
  
87
  /** Internal computed watch patterns (set automatically) */
88
  monitor?: string[];
89
  
90
  /** Internal spawn configuration (set automatically) */
91
  spawn?: boolean;
92
  
93
  /** Disable update notifications (default: false) */
94
  noUpdateNotifier?: boolean;
95
  
96
  /** Use legacy fs.watchFile instead of chokidar (default: false) */
97
  legacyWatch?: boolean;
98
  
99
  /** Polling interval for legacy watch mode in milliseconds */
100
  pollingInterval?: number;
101
  
102
  /** @deprecated JavaScript file watching (enabled by default) */
103
  js?: boolean;
104
  
105
  /** Suppress nodemon's own output (default: false) */
106
  quiet?: boolean;
107
  
108
  /** Path to nodemon configuration file */
109
  configFile?: string;
110
  
111
  /** Exit when child process crashes (default: false) */
112
  exitCrash?: boolean;
113
  
114
  /** Execution-specific options */
115
  execOptions?: NodemonExecOptions;
116
}
117
```
118

119
### Execution Configuration
120

121
Options for controlling how the monitored script is executed.
122

123
```javascript { .api }
124
interface NodemonExecOptions {
125
  /** Script file to execute (required) */
126
  script: string;
127
  
128
  /** Position of script in argument array */
129
  scriptPosition?: number;
130
  
131
  /** Arguments to pass to the script */
132
  args?: string[];
133
  
134
  /** File extensions to monitor (e.g., "js,json,ts") */
135
  ext?: string;
136
  
137
  /** Executable to use (node, python, etc.) */
138
  exec?: string;
139
  
140
  /** Arguments to pass to the executable */
141
  execArgs?: string[];
142
  
143
  /** Arguments to pass specifically to node */
144
  nodeArgs?: string[];
145
}
146
```
147

148
## Configuration Methods
149

150
### Object Configuration
151

152
Direct configuration using a settings object.
153

154
**Usage Examples:**
155

156
```javascript
157
const nodemon = require('nodemon');
158

159
// Basic configuration
160
nodemon({
161
  script: 'app.js',
162
  ext: 'js json',
163
  watch: ['src/', 'config/'],
164
  ignore: ['test/', 'logs/'],
165
  delay: 1000
166
});
167

168
// Advanced configuration
169
nodemon({
170
  script: 'server.js',
171
  exec: 'node --inspect',
172
  args: ['--port', '3000'],
173
  env: {
174
    NODE_ENV: 'development',
175
    DEBUG: 'myapp:*'
176
  },
177
  events: {
178
    restart: 'echo "Server restarted"',
179
    crash: 'echo "Server crashed"'
180
  },
181
  watchOptions: {
182
    followSymlinks: false,
183
    usePolling: false
184
  }
185
});
186

187
// Python script example
188
nodemon({
189
  script: 'app.py',
190
  exec: 'python',
191
  ext: 'py',
192
  watch: ['src/'],
193
  env: {
194
    PYTHONPATH: './src'
195
  }
196
});
197
```
198

199
### String Configuration
200

201
CLI-style string configuration for simpler setups.
202

203
**Usage Examples:**
204

205
```javascript
206
const nodemon = require('nodemon');
207

208
// Basic string configuration
209
nodemon('app.js');
210
nodemon('--ext js,json app.js');
211
nodemon('--watch src --ignore test app.js');
212

213
// Complex string configuration
214
nodemon('--exec "node --inspect" --ext js,ts --delay 2000 server.js');
215
```
216

217
### Configuration Files
218

219
Nodemon supports configuration files in multiple formats.
220

221
**nodemon.json:**
222

223
```json
224
{
225
  "watch": ["src/", "config/"],
226
  "ext": "js,json,ts",
227
  "ignore": ["test/", "*.test.js"],
228
  "exec": "node --inspect",
229
  "env": {
230
    "NODE_ENV": "development"
231
  },
232
  "events": {
233
    "restart": "echo 'App restarted'",
234
    "crash": "echo 'App crashed'"
235
  }
236
}
237
```
238

239
**package.json configuration:**
240

241
```json
242
{
243
  "name": "my-app",
244
  "nodemonConfig": {
245
    "watch": ["src/"],
246
    "ext": "js,json",
247
    "ignore": ["test/"]
248
  }
249
}
250
```
251

252
## Configuration Examples
253

254
### Web Development Setup
255

256
```javascript
257
nodemon({
258
  script: 'server.js',
259
  ext: 'js,json,html,css',
260
  watch: ['src/', 'public/', 'views/'],
261
  ignore: ['node_modules/', '*.test.js', 'logs/'],
262
  env: {
263
    NODE_ENV: 'development',
264
    PORT: '3000'
265
  },
266
  delay: 1000
267
});
268
```
269

270
### TypeScript Development
271

272
```javascript
273
nodemon({
274
  script: 'dist/app.js',
275
  watch: ['src/'],
276
  ext: 'ts',
277
  exec: 'npx ts-node src/app.ts',
278
  env: {
279
    NODE_ENV: 'development'
280
  }
281
});
282
```
283

284
### Multi-language Project
285

286
```javascript
287
nodemon({
288
  script: 'main.py',
289
  watch: ['src/'],
290
  ext: 'py,js,json',
291
  exec: 'python',
292
  execMap: {
293
    '.py': 'python3',
294
    '.rb': 'ruby'
295
  }
296
});
297
```
298

299
### Custom Events Configuration
300

301
```javascript
302
nodemon({
303
  script: 'app.js',
304
  events: {
305
    restart: 'npm run build',
306
    start: 'echo "Starting development server"',
307
    crash: 'npm run notify-crash'
308
  }
309
});
310
```
311

312
### Debugging Configuration
313

314
```javascript
315
nodemon({
316
  script: 'app.js',
317
  exec: 'node --inspect=0.0.0.0:9229',
318
  verbose: true,
319
  dump: false, // Set to true to see full config
320
  stdout: true
321
});
322
```
323

324
## Advanced Configuration
325

326
### Watch Options
327

328
Chokidar-specific options for fine-tuning file system monitoring.
329

330
```javascript
331
nodemon({
332
  script: 'app.js',
333
  watchOptions: {
334
    followSymlinks: false,
335
    usePolling: false,
336
    interval: 100,
337
    binaryInterval: 300,
338
    ignoreInitial: true,
339
    persistent: true,
340
    atomic: true
341
  }
342
});
343
```
344

345
### Signal Handling
346

347
Custom signal configuration for process management.
348

349
```javascript
350
nodemon({
351
  script: 'app.js',
352
  signal: 'SIGTERM', // Signal to send to child process
353
  stdout: false, // Capture stdout for custom processing
354
  stdin: false   // Disable stdin commands
355
});
356
```
357

358
### Environment-specific Configuration
359

360
```javascript
361
const isDev = process.env.NODE_ENV === 'development';
362

363
nodemon({
364
  script: 'app.js',
365
  verbose: isDev,
366
  delay: isDev ? 1000 : 0,
367
  ignore: isDev ? ['test/'] : ['test/', 'docs/'],
368
  env: {
369
    NODE_ENV: process.env.NODE_ENV || 'development',
370
    DEBUG: isDev ? 'myapp:*' : ''
371
  }
372
});
373
```
374

375
## Configuration Priority
376

377
Nodemon resolves configuration in the following order (highest to lowest priority):
378

379
1. Command line arguments
380
2. Programmatic configuration object
381
3. Local nodemon.json
382
4. package.json nodemonConfig
383
5. Global nodemon.json (`~/.nodemon.json`)
384
6. Default values
385

386
## Notes
387

388
- Configuration is merged from multiple sources with CLI args taking highest priority
389
- File paths in configuration are relative to the working directory
390
- Environment variables can be set via the `env` option
391
- The `events` option allows running shell commands on nodemon events
392
- Watch patterns support glob syntax for flexible file matching
393
- Configuration can be dumped for debugging using the `dump: true` option