src: add built-in .env file support

[anonrig]

Follow-ups in #49148

Follow-up from the comments:

@cjihrig:

• Using a custom path instead of .env file in the current working directory.
• The option to augment vs. overwrite the existing process.env with the values from the .env file. If we support augmenting, what happens on conflict (overwrite, don’t overwrite, throw, etc.)?
• Programmatic API.
• The ability to put the loaded values in an object other than process.env.
• Multiline values.
• Comments in the .env files.
• Variable expansion.

@KhafraDev

• regarding testing and validation, you can take dotenv’s test suite https://github.com/motdotla/dotenv/tree/master/tests

@GeoffreyBooth

• the flag should be –env-file [path-to-file] so like –env-file .env or –env-file .env.development or whatever.
• fix and support windows newline character
• Support NODE_OPTIONS

Missing features

The following features are not implemented in this current context. And can be implemented in a separate PR.

• Respect newline character in values with "
• Multiline values
• Variable expansion
• Incremental env support (.env.development overrides .env on NODE_ENV=development)

Ref: https://github.com/orgs/nodejs/discussions/44975

[nodejs-github-bot]

Review requested:

• @nodejs/startup

[cjihrig]

I think we'll get a number of follow up requests beyond the most basic functionality. A few that I think we should have some plan for:

• Using a custom path instead of .env file in the current working directory.
• The option to augment vs. overwrite the existing process.env with the values from the .env file.
• If we support augmenting, what happens on conflict (overwrite, don't overwrite, throw, etc.)?
• Programmatic API.
• The ability to put the loaded values in an object other than process.env.
• Multiline values.
• Comments in the .env files.
• Variable expansion.

Note, some of these are taken directly from the dotenv module's README.

[KhafraDev]

regarding testing and validation, you can take dotenv's test suite (which afaik is the most popular package for parsing .env files): https://github.com/motdotla/dotenv/tree/master/tests

my other concerns were already mentioned just before I was about to comment

[GeoffreyBooth]

Thank you for doing this! My vote is that the flag should be --env-file [path-to-file] so like --env-file .env or --env-file .env.development or whatever, so that people can have multiple files per environment like how Bun handles this. If we’re going to require a flag at all, we might as well make it versatile.

And a future PR can potentially add support for configuring Node without needing opt in via flag, like potentially a node.config.json file or a field in package.json; but those implementations can live alongside this one.

[GeoffreyBooth]

I think we’ll get a number of follow up requests beyond the most basic functionality.

I think it’s okay if we define our scope as more limited than dotenv‘s, and if people want something more full-featured then they should just use dotenv. Ultimately the point of adding this is to fix #48852 and #43973, to just provide a way to configure Node, and the ability to set other environment variables beyond NODE_OPTIONS is a side benefit.

That said, from your list I already mentioned allowing specifying the path to the file, and I think we need to at least document what we do for conflicts; I think the simplest approach is to just always have the “real” environment variable win out over whatever is defined in the file, and leave it at that. It would be nice to ignore lines starting with # as comments, as that should hopefully be pretty easy. The rest I think we could consider out of scope, at least for now.

One other thing we should do is mark this as experimental in the docs.

[himself65]

There is a question: how about .env.local .env.*.local …

there will have multiple different env file during the development

[kibertoad]

Supporting incremental .env files would be great (e. .env.test with overrides over generic .env)

[bnoordhuis]

See, the feature requests already start piling up...

Apart from this being an infinitely slippery slope, I also feel it goes directly against node's "mechanism over policy" philosophy. Not a fan.

[QuadTriangle]

Please consider adding support for env expand. It's insane to think that dotenv-expand has 12 million weekly download which has no defined grammer.

test$var
test${var
test$var}
test$var:-$hmm
test${var:-$hmm

the list goes on. Too much regex in Node community 🙂

[anonrig]

Please consider adding support for env expand. It's insane to think that dotenv-expand has 12 million weekly download which has no defined grammar.

I think it can be implemented as a follow-up pull request, if anyone is interested in implementing. I'm in favor of keeping the implementation as small as possible (for now).

[panva]

What is this feature's interaction with the permission model?

[anonrig]

What is this feature's interaction with the permission model?

@panva If we want to support NODE_OPTIONS, it needs to bypass permission model, since V8 will not be initialized at that time.

[ovflowd]

@panva If we want to support NODE_OPTIONS, it needs to bypass permission model, since V8 will not be initialized at that time.

So an env variable that pretty much can override node options... That is honestly risky in many fronts even more when it boils down to bypassing permission mode options.

[Trott]

@nodejs/tsc This seems like the kind of thing the TSC should have an opinion on.

[mikemaccana]

Thanks @anonrig! You've saved a few hundred thousand people (maybe more) a little work by including this! ❤️

[jaylinski]

@anonrig Was it a deliberate decision to not set kAllowedInEnvvar for this option?

I'm asking, because in order to replace the dotenv-npm-package with the native dotenv-package (this feature) AND using npm scripts, I need to set NODE_OPTIONS='--env-file .env' in my .npmrc file.

Currently, this is not possible because kAllowedInEnvvar is not set.

[anonrig]

It wasn't a deliberate decision. Prs are welcome :-)

[GeoffreyBooth]

Is there a risk of a loop here? Like what if an .env file contains NODE_OPTIONS='--env-file .env'?

[anonrig]

No there isn't

[jaylinski]

Thanks for the info! I'll read through the contribution guidelines and open a PR.

[GeoffreyBooth]

it would be really useful when running node-scripts via npm

How so? What is a script you would use it for?

[jaylinski]

How so? What is a script you would use it for?

In my case I'm running playwright via npm like this:

package.json

{"name": "npm-package", "scripts":{"test:browser": "playwright test" } }

Inside my playwright config, I'm currently using dotenv.config() to get the baseUrl for the current env.

playwright.config.ts

importdotenvfrom'dotenv';dotenv.config();constconfig: PlaywrightTestConfig={baseURL: process.env.PLAYWRIGHT_BASE_URL,};exportdefaultconfig;

I'd like to get rid of the npm dotenv-dependency and use the native Dotenv functionality, without having to change my npm scripts to something like node --env-file=.env node_modules/.bin/playwright test.

[GeoffreyBooth]

without having to change my npm scripts to something like node --env-file=.env node_modules/.bin/playwright test

So you're saying you prefer to do NODE_OPTIONS=--env-file=.env playwright test? Node doesn't automatically load .env files.

[jaylinski]

So you're saying you prefer to do NODE_OPTIONS=--env-file=.env playwright test? Node doesn't automatically load .env files.

Yes, sort of.

As far as i know, I can use .npmrc and node-options to automatically apply NODE_OPTIONS to called lifecycle scripts (like playwright).

[GeoffreyBooth]

As far as i know, I can use .npmrc and node-options to automatically apply NODE_OPTIONS to called lifecycle scripts (like playwright).

Interesting, I didn’t know about node-options!

[zanminkian]

Which is the standard or recommended file pattern? .env.foo or .foo.env? Corepack and Node official document prefer the later one.

Refer to https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs

[anonrig]

Which is the standard or recommended file pattern? .env.foo or .foo.env? Corepack and Node official document prefer the later one.

Refer to https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs

.foo.env is the preferred one

[zanminkian]

A further suggestion:

We should treat .env as a file extension. Therefore, disallowing the files with non .env extension for --env-file will benefit Node community.