# Replace nodemon With node --watch in an Express and Mongoose API

Yes. An agent swaps nodemon for node --watch, fixes the shutdown handler that would make every restart hang, and opens a pull request showing restarts work.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-nodemon-to-node-watch/nodemon/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the dev server is started and stopped before it changes a script. In an API like hagopj13/node-express-boilerplate the `dev` script is `cross-env NODE_ENV=development nodemon src/index.js`, there is no `nodemon.json`, and `yarn.lock` holds nodemon 2.0.9. `docker-compose.dev.yml` runs `yarn dev -L`, which is nodemon's legacy polling mode for the bind mount in `docker-compose.yml`. `src/index.js` connects Mongoose, starts the HTTP server, and on `SIGTERM` logs a line and calls `server.close()`. `engines.node` still says `>=12.0.0`.

It then runs both tools against the real app, with a MongoDB it installs in the sandbox. nodemon prints that it watches `*.*` with extensions `js,mjs,json` and restarts when a file under `src` changes. The naive replacement, `node --watch src/index.js`, starts the same way, but the first edit goes wrong: Node prints `Restarting 'src/index.js'`, the app logs `SIGTERM received`, Node prints `Waiting for graceful termination...`, and nothing else happens. When this page was written, on Node 22.23.4, the old process was still there 30 seconds later and the new one never started. The cause is in the handler. nodemon restarts with `SIGUSR2`, which this app does not handle, so the process dies at once. `node --watch` sends `SIGTERM`, the handler closes the HTTP server, and the open Mongoose connection keeps the process alive.

There are two fixes and the agent tests both. Adding `mongoose.disconnect()` to the `SIGTERM` handler lets the process exit, and restarts then work with the default signal. Passing `--watch-kill-signal=SIGUSR2` restores nodemon's behaviour with no code change, but that flag was added in Node 22.18 and its documentation marks it as under active development. The agent takes the handler fix, because the same hang affects any supervisor that stops this app with `SIGTERM`, and mentions the flag as the alternative.

Last come the differences that do not show up as errors. `node --watch` follows the entry file and the modules it requires, so a file nothing imports no longer triggers a restart. It has no `rs` command and no polling mode: `node --help` lists `--watch`, `--watch-path`, `--watch-kill-signal` and `--watch-preserve-output`. `yarn dev -L` would therefore hand `-L` to the app as an argument, where it is ignored. The agent changes the Compose command to `yarn dev`, says polling is gone, and names the fallback. It raises `engines.node` to 22, where watch mode is stable, removes nodemon from `package.json` and `yarn.lock`, and runs the Jest suite to confirm the handler change broke nothing.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace nodemon with Node's built-in watch mode in this Express and Mongoose API. Read package.json, yarn.lock, src/index.js, the docker-compose files and the README first. There is no Docker here: install a MongoDB server, start mongod on 127.0.0.1:27017 and copy .env.example to .env. Start the app with the current dev script, edit a file under src and record what nodemon prints. Then start it with node --watch, make the same edit and record what happens, waiting at least 30 seconds. If the restart does not complete, find out which signal each tool sends and what the SIGTERM handler in src/index.js leaves open, fix the handler so the process exits, and show the restart completing. Also test --watch-kill-signal and report which Node version it needs. Report what node --watch does on a syntax error, whether it restarts when .env changes, and what happens to the -L flag in docker-compose.dev.yml. Change the dev script, raise engines.node to a version where watch mode is stable, remove nodemon from package.json and the lockfile, update the README, and run yarn test before and after. Open a pull request with the output of every command.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes the `dev` script, the `SIGTERM` handler in `src/index.js`, `docker-compose.dev.yml`, `engines.node`, `yarn.lock` and the README. The description is mostly transcripts: nodemon restarting on an edit, the unfixed `node --watch` stuck at `Waiting for graceful termination...`, and the fixed version logging `SIGTERM received` followed by `Listening to port 3000` again. It also shows what a broken file looks like, where Node prints `Failed running 'src/index.js'. Waiting for file changes before restarting...` and recovers on the next save.

The reviewer decides two things. One is the handler: disconnecting Mongoose on `SIGTERM` changes how the app stops in production too, under pm2 and under a container runtime, and that is the intended effect but still a behaviour change. The other is Docker development. On a Linux host file events cross the bind mount; on a host where they do not, the dev container will stop restarting, and the description says to keep nodemon in that one Compose file if your team needs polling. The agent cannot test Docker Desktop from a Linux sandbox and says so.

## Run it on every service that still starts with nodemon

The swap is done once per service. If your org has many, list the repositories whose `package.json` has a `nodemon` script and send this body to `POST /o/{org}/sessions` once for each, with that repository in `resources`. Include a `request_id` that is a UUID v5 of the repository's full name, so a second pass over the list starts nothing new for a repository that already has a run.

To hand single services over as they come up, add an automation on the Project with a `github` trigger on `issues.labeled` and a label such as `drop-nodemon`, and save this prompt on it. The issue is added after the prompt as event text. Only an owner, member or collaborator of the repository fires the trigger.

## Why run it on Rush?

The failure this job has to find does not appear in a diff or a type check. It appears when a real server with a real database connection receives a real signal. The agent has its own machine for that: it installs MongoDB, starts the app under each watcher, edits a file and waits. The stuck restart, the signal each tool sends and the fix are all observed, and the run keeps each command with what it printed.

It is also a job where a laptop gives a misleading answer. A developer who tries `node --watch` on a small script sees it work and concludes the swap is a one-line change. The hang depends on this app's handler and its open connection. Running the service itself, in a clean sandbox with nothing else on port 3000, is what turns the swap from a guess into a tested change with the evidence attached to the pull request.

## Frequently asked questions

### Does node --watch restart when .env changes?

Only if Node loads the file itself. Started as `node --watch --env-file=.env src/index.js` on Node 22.23.4, the app restarted after an edit to `.env`. With dotenv reading the file at run time it is not a module, so watch mode does not follow it. nodemon 2.0.9 did not restart on that edit either, since `env` is not one of its default extensions.

### Is --watch-path the same as nodemon's --watch option?

It is close: it names directories to watch and turns off following required modules. The Node 22 documentation says the option is supported only on macOS and Windows. On Linux with Node 22.23.4, `--watch-path=src` did restart this app after an edit, but the agent does not build the dev script on behaviour the documentation excludes.

### What replaces nodemon's rs command?

Nothing. Watch mode has no manual restart, so you save a file or stop and start the process. A change it cannot see, such as an edit to a file that nothing imports, needs one of those two. For a `.env` file, passing it with `--env-file` makes Node watch it.

### Which Node version do I need?

Watch mode was added in Node 18.11 and became stable in 22.0. `--watch-kill-signal` needs 22.18. A repository whose `engines` field allows Node 12, as this one does, has to raise it in the same change.

## More jobs like this: Hand off a long task

- [Replace nyc with c8 for Code Coverage in a Node.js Library](https://getrush.ai/run/migrate-nyc-to-c8/nyc/)
- [Migrate a Python CLI From optparse to argparse](https://getrush.ai/run/migrate-optparse-to-argparse/optparse/)
- [Migrate a grammY Bot From Long Polling to Webhooks](https://getrush.ai/run/migrate-polling-to-webhooks/grammy/)
- [Migrate Puppeteer Scripts to Playwright](https://getrush.ai/run/migrate-puppeteer-to-playwright/puppeteer/)
- [Migrate a SolidJS App from Rollup to Vite](https://getrush.ai/run/migrate-rollup-to-vite/solidjs/)
- [Migrate a Python Project from setup.py to pyproject.toml](https://getrush.ai/run/migrate-setup-py-to-pyproject/python/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
