src: add built-in `.env` file support by anonrig · Pull Request #48890 · nodejs/node · GitHub

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

Review requested:

@nodejs/startup

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.

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

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.

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.

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

there will have multiple different env file during the development

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

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.

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 🙂

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).

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

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.

@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.

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

CI: https://ci.nodejs.org/job/node-test-pull-request/53393/

CI: https://ci.nodejs.org/job/node-test-pull-request/53394/

LGTM!
Amazing, thanks for this!

Landed in 769823e

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

@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.

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

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

No there isn't

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

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

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

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

import dotenv from 'dotenv';

dotenv.config();

const config: PlaywrightTestConfig = {
	baseURL: process.env.PLAYWRIGHT_BASE_URL,
};

export default config;

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.

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.

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).

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!

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

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

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.

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jul 23, 2023

anonrig added the blocked PRs that are blocked by other issues or PRs. label Jul 23, 2023

anonrig force-pushed the dotenv-support branch from f41af8e to 6a73a72 Compare July 23, 2023 04:30

GeoffreyBooth reviewed Jul 23, 2023

View reviewed changes

Comment thread src/node_dotenv.cc Outdated

Comment thread test/fixtures/dotenv/valid/.env Outdated

GeoffreyBooth marked this pull request as draft July 23, 2023 05:15

GeoffreyBooth removed the blocked PRs that are blocked by other issues or PRs. label Jul 23, 2023

GeoffreyBooth mentioned this pull request Jul 23, 2023

Update README.md nodejs/loaders#152

Merged

himself65 reviewed Jul 23, 2023

View reviewed changes

anonrig force-pushed the dotenv-support branch 2 times, most recently from 97aacf7 to 5b5dcc9 Compare July 23, 2023 18:50

GeoffreyBooth reviewed Jul 23, 2023

View reviewed changes

Comment thread doc/api/cli.md Outdated

Comment thread doc/api/cli.md Outdated

Comment thread src/node_dotenv.cc Outdated

Comment thread src/node_options.cc Outdated

anonrig force-pushed the dotenv-support branch 2 times, most recently from e00e3e8 to 0541c35 Compare July 23, 2023 20:11

GeoffreyBooth reviewed Jul 23, 2023

View reviewed changes

Comment thread doc/api/cli.md Outdated

RaisinTen reviewed Jul 24, 2023

View reviewed changes

Comment thread test/fixtures/dotenv/valid.env Outdated

MoLow added the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Jul 24, 2023

ShogunPanda approved these changes Aug 17, 2023

View reviewed changes

anonrig added the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 17, 2023

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Aug 17, 2023

UlisesGascon mentioned this pull request Aug 17, 2023

v20.6.0 proposal #49185

Merged

RafaelGSS mentioned this pull request Aug 17, 2023

Load permission settings from config files nodejs/security-wg#1074

Closed

This was referenced Aug 18, 2023

CI Reliability 2023-08-18 nodejs/reliability#640

Open

CI Reliability 2023-08-21 nodejs/reliability#641

Open

mihaiplesa mentioned this pull request Aug 21, 2023

Use native nodejs 20 .env support brave/brave-browser#32420

Open

github-actions Bot mentioned this pull request Aug 22, 2023

CI Reliability 2023-08-22 nodejs/reliability#642

Open

21 tasks

This was referenced Aug 29, 2023

feat(env-options): env-options conveniences for common cases endojs/endo#1710

Merged

fix: DEBUG harmony Agoric/agoric-sdk#8136

Merged

Inconsistency between endo vs agoric-sdk on syntax of DEBUG options Agoric/agoric-sdk#8096

Closed

philnash mentioned this pull request Sep 1, 2023

src: don't overwrite environment from .env file #49424

Merged

jaylinski reviewed Sep 26, 2023

View reviewed changes

RafaelGSS mentioned this pull request Oct 6, 2023

doc: mention files read before env setup #50072

Merged

ALegchilov mentioned this pull request Jan 9, 2024

Add a feature to parse .env file by default #51413

Closed

Tobbe mentioned this pull request Feb 9, 2024

Add support for additional env var files redwoodjs/graphql#9961

Merged

soc221b mentioned this pull request Sep 27, 2024

Feature: integrate built-in .env file support runtime-env/runtime-env#176

Closed

zanminkian mentioned this pull request Apr 21, 2025

Add syntax highlighting for .*.env files microsoft/vscode#247055

Closed

zanminkian mentioned this pull request Apr 21, 2025

feat(eslint-config): support linting .*.env files and disallowing .env.* files zanminkian/fenge#378

Closed

This was referenced Jun 24, 2025

Extend --env-file with support for INI sections #58729

Closed

node env file parsing supports keys compared to dotenv #58807

Closed

coderabbitai Bot mentioned this pull request Mar 19, 2026

Feat(extension, client): extension dist discord webhook Pinback-Team/pinback-client#322

Merged

4 tasks

+                    "[has_env_file_string]", "", &EnvironmentOptions::has_env_file_string);
+                AddOption("--env-file",
+                          "set environment variables from supplied file",
+                          &EnvironmentOptions::env_file);

src: add built-in `.env` file support by anonrig · Pull Request #48890 · nodejs/node · GitHub

Uh oh!

Uh oh!

src: add built-in .env file support - #48890

src: add built-in .env file support#48890nodejs-github-bot merged 15 commits intonodejs:mainnodejs/node:mainfrom anonrig:dotenv-supportanonrig/node:dotenv-supportCopy head branch name to clipboard

Conversation

anonrig commented Jul 23, 2023 • edited by GeoffreyBooth Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Follow-up from the comments:

Missing features

Uh oh!

nodejs-github-bot commented Jul 23, 2023

Uh oh!

cjihrig commented Jul 23, 2023

Uh oh!

KhafraDev commented Jul 23, 2023

Uh oh!

GeoffreyBooth left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

GeoffreyBooth commented Jul 23, 2023

Uh oh!

himself65 left a comment

Choose a reason for hiding this comment

Uh oh!

kibertoad commented Jul 23, 2023

Uh oh!

bnoordhuis commented Jul 23, 2023

Uh oh!

QuadTriangle commented Jul 23, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anonrig commented Jul 23, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

panva commented Jul 24, 2023

Uh oh!

Uh oh!

anonrig commented Jul 24, 2023

Uh oh!

ovflowd commented Jul 24, 2023

Uh oh!

Trott commented Jul 24, 2023

Uh oh!

nodejs-github-bot commented Aug 17, 2023

Uh oh!

nodejs-github-bot commented Aug 17, 2023

Uh oh!

ShogunPanda left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Aug 17, 2023

Uh oh!

mikemaccana commented Sep 6, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaylinski Sep 26, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

package.json

playwright.config.ts

src: add built-in .env file support#48890
nodejs-github-bot merged 15 commits into
nodejs:mainfrom
anonrig:dotenv-support

anonrig commented Jul 23, 2023 •
edited by GeoffreyBooth
Loading

GeoffreyBooth left a comment •
edited
Loading

QuadTriangle commented Jul 23, 2023 •
edited
Loading

mikemaccana commented Sep 6, 2023 •
edited
Loading

jaylinski Sep 26, 2023 •
edited
Loading

GeoffreyBooth Sep 27, 2023 •
edited
Loading

zanminkian commented Apr 21, 2025 •
edited
Loading