node --watch: restart the app when a file changes (no nodemon)

node --watch app.js runs the script and restarts it every time the entry file or any module it imported changes on disk. It is built into Node.js since 18.11.0 (stable since 22.0.0 and 20.13.0), so the nodemon package is no longer needed for the usual "restart the server on save" workflow. By default Node.js clears the console on each restart; --watch-preserve-output keeps the previous output.

Restart on change

The script prints a line; one second later the block edits it, and --watch reruns it. timeout stops the watcher after four seconds (exit code 124):

cat > app.js <<'EOF'
console.log("version 1");
EOF
(sleep 1.5; echo 'console.log("version 2");' > app.js) &
timeout 4 node --watch --watch-preserve-output app.js

version 1
Completed running 'app.js'. Waiting for file changes before restarting...
Change detected in '/tmp/work/app.js'
Restarting 'app.js'
version 2
Completed running 'app.js'. Waiting for file changes before restarting...

When the program exits on its own, Node.js prints Completed running 'app.js' and keeps waiting; when a long-running server is restarted, the old process is stopped first, so the port is free for the new one.

Related flags

--watch-path is useful when the program reads files at runtime (templates, JSON, SQL) that are never imported: node --watch-path=./src --watch-path=./views server.js. Note that it replaces the module tracking instead of adding to it.

In package.json

{
  "scripts": {
    "dev": "node --watch --env-file=.env src/server.js",
    "start": "node src/server.js"
  }
}

Keep --watch out of the production start script: it adds file system watchers and restarts the process when a deploy writes files.

Pitfalls and limits

• --watch cannot be combined with --check, --eval, --interactive or the REPL; it needs a script file.
• In watch mode Node.js waits for the old process to exit. A server that ignores SIGTERM delays every restart.
• On network shares, some containers and WSL mounts of Windows folders, file change events may not arrive; editing inside the container's own file system or using a polling watcher such as nodemon's legacy mode helps.
• Older releases that only had --watch as experimental print an ExperimentalWarning; it is harmless.
• --watch-path is not supported on every platform in older releases (it needs recursive fs.watch, which Linux gained in Node.js 20).

For TypeScript, combine the flag with type stripping: see run a TypeScript file with Node.js.

FAQ