So you’re working on a Node.js application and getting awfully tired of restarting the process every time you make a change? Enter nodemon, a CLI utility developed by @rem that wraps your Node app, watches the file system for changes and automatically restarts the process.
Getting started with nodemon is as simple as it gets. Install the utility either globally or locally to your project using npm or Yarn:
Global install
$ yarn global add nodemon # or, using npm: $ npm install nodemon -g
Local install
$ yarn add nodemon --dev # or, using npm: $ npm install nodemon --save-dev
As you can see, when doing a local install, we can install as a dev dependency. Note also that with a local install you won’t be able to use the nodemon command directly from the command line, but instead you can use it as part of some npm scripts, or with npx.
Basic Usage
It’s just as easy to use nodemon as it is to start a Node script. In fact, the same exact arguments can be passed-in to nodemon. For example, if we have a simple Express server setup in a server.js
file, we can start it and watch for changes like this:
$ nodemon server.js
Arguments can be passed-in the same way as if you were running the script with Node:
$ nodemon server.js 3006
Now every time a change is made to a file with one of the default watched extensions (.js, .mjs, .json, .coffee or .litcoffee) in the current directory or a subdirectory, the process will restart:
Don't worry, the node_modules folder is ignored by default.
As you can see from the screenshot above, the terminal output from your Node.js app is displayed normally. You can restart the process at any time by typing rs and hitting enter.
Alternatively, nodemon will also look for a main file specified in your project’s package.json
file or a start script. Given either of the examples below, you can then simply call $ nodemon
to start your app in watch mode:
Main file
package.json
{ ... "main": "server.js", ... }
Start script
package.json
{ ... "scripts": { "start": "node server.js" }, ... }
Advanced Options
There are a bunch of options available, and you can access a summary of the available options with $ nodemon -h
.
Let’s go over a few of the main options:
--exec
: Use --exec
to specify a binary to execute the file with. For example, when combined with the ts-node binary, --exec
can become really useful to watch for changes and run TypeScript files. --ext
: Specify different file extensions to watch. For this switch, provide a comma-separated list of file extensions (e.g.: --ext js,ts
). --delay
: By default nodemon waits for 1 second to restart the process when a file changes, but with --delay
you can specify a different delay. For example, $ nodemon --delay 3.2
for a 3.2 second delay. --watch
: Use the --watch
switch to specify multiple directories or files to watch. Add one --watch
switch for each directory you want to watch. By default the current directory and its subdirectories are watched, so with --watch
you can narrow that to only specific subdirectories or files. --ignore
: Use --ignore
to ignore certain files, file patterns or directories. --verbose
: A more verbose output with information about what file(s) changed to trigger a restart.
Below, for example, we’re watching the server directory for files with a .ts extension, ignoring files with a .test.ts suffix, executing the file (server/server.ts
) with ts-node and waiting for 3 seconds to restart after a file changes:
$ nodemon --watch server --ext ts --exec ts-node --ignore '*.test.ts' --delay 3 server/server.ts
Config
As you saw from the above example, adding configuration switches when running nodemon can get quite tedious. A better solution for projects that need specific configurations is to specify these configs in a nodemon.json
file. For example, below are the same configurations as the above example, but placed in a nodemon config file:
nodemon.json
{ "watch": ["server"], "ext": "ts", "ignore": ["*.test.ts"], "delay": "3", "execMap": { "ts": "ts-node" } }
Note the use of execMap instead of the --exec
switch. execMap allows to specify binaries that should be used given certain file extensions.
With this, you can simply start nodemon with the desired script:
$ nodemon server/server.ts
Alternatively, if you’d rather not add a nodemon.json
config file to your project, you can add these configurations to the package.json
file under a nodemonConfig key:
package.json
{ "name": "test-nodemon", "version": "1.0.0", "description": "", "nodemonConfig": { "watch": [ "server" ], "ext": "ts", "ignore": [ "*.test.ts" ], "delay": "3", "execMap": { "ts": "ts-node" } }, ...