All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

Keep reading