All jobs

Replace dotenv With Node's --env-file Flag in an Express App

Yes. An agent removes dotenv, loads .env with Node's --env-file flag in every script that starts the app, and opens a pull request with the suite passing.

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 starts by listing every way the app is launched, because dotenv hides that list. In an Express API like hagopj13/node-express-boilerplate, src/config/config.js calls dotenv.config({ path: path.join(__dirname, '../../.env') }) and then validates process.env with a Joi schema that requires NODE_ENV, MONGODB_URL and JWT_SECRET. That single call serves four launchers: yarn dev (cross-env and nodemon), yarn start (pm2 reading ecosystem.config.json), yarn test (Jest, in band) and the Docker Compose files, which mount the repository and set MONGODB_URL themselves. yarn.lock holds dotenv 10.0.0, engines.node says >=12.0.0, and .travis.yml builds on Node 12 with the variables in env.global and no .env file at all.

Next it checks that Node reads the file the way dotenv does. On the 12 keys of .env.example, dotenv 10.0.0 and Node 22 return the same values. They part ways on input the example does not contain. For the line A=pa#ss, dotenv 10 returns pa#ss and Node returns pa, since Node treats everything after an unquoted # as a comment. dotenv 10 skips a line that begins with export; Node reads it. Both leave a variable alone when the environment already has it, which is what the Compose file depends on. The agent searches the .env files it can see for an unquoted # in a value and names each one, because a password containing that character must be quoted after this change.

The shortest patch, a process.loadEnvFile() call in config.js, fails here in a way that is easy to miss. Under this repository's Jest 26.6.3 the call sets the variables in the real environment but not in the copy of process.env Jest gives each test file. In band, the first suite to load fails with Config validation error: "MONGODB_URL" is required and the suites after it pass, so the number of failures depends on file order. process.loadEnvFile also throws when the file is missing, where dotenv.config returns an error object this code never reads. So the agent deletes the loading from config.js and moves it to the launchers.

test becomes node --env-file-if-exists=.env node_modules/jest/bin/jest.js -i with the existing flags, dev runs nodemon with --exec "node --env-file=.env", and ecosystem.config.json gains "node_args": "--env-file=.env", since pm2 and not a script starts src/index.js. Without that entry pm2 5.1.0 restarts the app until it gives up with too many unstable restarts (16). NODE_OPTIONS is no shortcut: Node answers --env-file= is not allowed in NODE_OPTIONS. The agent raises engines.node, moves .travis.yml off Node 12, removes dotenv from package.json and yarn.lock, and runs the suite against a MongoDB it installs in the sandbox. When this page was written the unchanged repository passed 113 tests on Node 22, and the same 113 passed with the flag in place.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace the dotenv package in this Express API with Node's built-in --env-file support. First read src/config/config.js, package.json, yarn.lock, ecosystem.config.json, jest.config.js, .env.example, .travis.yml, the Dockerfile and the docker-compose files, and list every command that starts the app or the tests. Compare how the installed dotenv version and this Node version parse .env.example, and report any difference on unquoted # characters, export prefixes and quotes. Do not call process.loadEnvFile inside config.js: show what it does under this repository's Jest version first. Remove the dotenv require and call from config.js and load the file from each launcher instead: the test script with --env-file-if-exists, the dev script through nodemon's --exec, and pm2 through node_args in ecosystem.config.json. Raise engines.node to a version that has the flags you used, update the CI Node version, remove dotenv from package.json and the lockfile, and fix the README line that names it. There is no Docker here: install a MongoDB server, start mongod on 127.0.0.1:27017, copy .env.example to .env and run yarn test before and after. Start the app once with each launcher and show that the config loads. 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 touches src/config/config.js, package.json, yarn.lock, ecosystem.config.json, .travis.yml and the README. Its description holds the launcher list, the parser comparison as a small table of inputs and the value each parser returned, and the Jest output before and after. It also shows the three starts: nodemon printing its starting line with the flag, pm2 reaching Listening to port 3000, and Jest passing with and without a .env file present, the second with the variables supplied by the shell the way CI supplies them.

A reviewer checks three things the diff cannot prove. The first is the Node version that production runs: the Dockerfile says FROM node:alpine with no tag, and the flag needs Node 20.6, or 22.9 for the -if-exists form. The second is any process that imports config.js outside these launchers, such as a one-off script or a debugger configuration, which now starts with no variables unless it passes the flag. The third is real secrets: a value with an unquoted # is read differently, and only the owner of the production .env can look.

Run it on every repository that still loads dotenv

This is a one-time change per repository, so the event is each service in your org that still requires dotenv. A short script on your side lists those repositories and sends this body once for each to POST /o/{org}/sessions, with the repository in resources. Send a request_id that is a UUID v5 of the repository name and the job name, so running the script twice returns the runs it already started.

A key runs at most max_concurrent runs at once, four by default. Requests past that are still accepted: each answers 202 with status: "queued" and starts when a slot frees, so the script needs no retry loop. If the key has a webhook_url, every run it starts posts run.completed or run.failed there when its turn ends, and the script can read each run's session_url from those to collect the pull request links.

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

Why run it on Rush?

The answer to "is it safe to drop dotenv" is in behaviour, not in the diff. Whether Jest sees the variables, whether pm2 passes a Node flag through, whether a # survives parsing: each needs the real tool at the version the lockfile pins, plus a database for the suite to talk to. The agent has a sandbox where it installs those, runs every launcher and keeps the output. The pull request then states what happened under each one.

It also runs the dead end on purpose. The process.loadEnvFile variant looks correct and passes most of the suite, and a person trying it on a laptop might see green on a lucky file order. In the sandbox the agent runs it, records the failure and the reason, and backs it out. That record stays with the run, so the next person who suggests the shorter patch can read why it was not taken.

Frequently asked questions

Which Node version does this need?

--env-file was added in Node 20.6 and --env-file-if-exists in 22.9, and both stopped being experimental in 22.21. A repository whose engines field still allows Node 12, like this one, has to raise it in the same pull request. The agent picks the lowest version that has every flag it used and says so.

Does --env-file override variables that are already set?

No. When the same variable is in the environment and in the file, the environment wins, which matches dotenv's default. That is why a Compose service that sets MONGODB_URL keeps its own value even though the mounted repository contains a .env file.

Why not keep one loading call in the config module?

Because of the test runner. Under Jest 26, process.loadEnvFile() changes the real environment while each test file reads a copy made earlier, so the first suite fails validation and later ones pass. Loading the file before Jest starts, with the flag on the node command, gives every suite the same environment.

Can I put the flag in NODE_OPTIONS instead of editing each script?

No. Node refuses it with --env-file= is not allowed in NODE_OPTIONS and exits with code 9. Each launcher needs the flag on its own command line, or in the launcher's own setting such as pm2's node_args.

More jobs like this: Hand off a long task

Keep reading