src: swap dotenv and config file parsing order

marco-ippolito · web-flow · commit 59272da05588 · 2026-05-04T06:39:18.000Z
Signed-off-by: Marco Ippolito <marcoippolito54@gmail.com> PR-URL: #63035 Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1143,12 +1143,12 @@ node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolat
 The priority in configuration is as follows:
 
 1. NODE\_OPTIONS and command-line options
-2. Configuration file
-3. Dotenv NODE\_OPTIONS
+2. Dotenv NODE\_OPTIONS
+3. Configuration file
 
 Values in the configuration file will not override the values in the environment
-variables and command-line options, but will override the values in the `NODE_OPTIONS`
-env file parsed by the `--env-file` flag.
+variables, command-line options, or the `NODE_OPTIONS` env file parsed by the
+`--env-file` flag.
 
 Keys cannot be duplicated within the same or different namespaces.
 
diff --git a/src/node.cc b/src/node.cc
@@ -870,6 +870,7 @@ static ExitCode InitializeNodeWithArgsInternal(
   HandleEnvOptions(per_process::cli_options->per_isolate->per_env);
 
   std::string node_options;
+  std::string node_options_from_dotenv;
   auto env_files = node::Dotenv::GetDataFromArgs(*argv);
 
   if (!env_files.empty()) {
@@ -896,7 +897,8 @@ static ExitCode InitializeNodeWithArgsInternal(
       }
     }
 
-    per_process::dotenv_file.AssignNodeOptionsIfAvailable(&node_options);
+    per_process::dotenv_file.AssignNodeOptionsIfAvailable(
+        &node_options_from_dotenv);
   }
 
   std::string node_options_from_config;
@@ -932,9 +934,10 @@ static ExitCode InitializeNodeWithArgsInternal(
       errors->emplace_back("The number of NODE_OPTIONS doesn't match "
                            "the number of flags in the config file");
     }
-    node_options += node_options_from_config;
   }
 
+  node_options = node_options_from_config + node_options_from_dotenv;
+
 #if !defined(NODE_WITHOUT_NODE_OPTIONS)
   bool should_parse_node_options =
       !(flags & ProcessInitializationFlags::kDisableNodeOptionsEnv);
diff --git a/src/node_dotenv.cc b/src/node_dotenv.cc
@@ -356,7 +356,7 @@ void Dotenv::AssignNodeOptionsIfAvailable(std::string* node_options) const {
   auto match = store_.find("NODE_OPTIONS");
 
   if (match != store_.end()) {
-    *node_options = match->second;
+    *node_options = " " + match->second;
   }
 }
 
diff --git a/test/parallel/test-config-file.js b/test/parallel/test-config-file.js
@@ -86,16 +86,16 @@ test('should throw an error when a flag is declared twice', async () => {
   assert.strictEqual(result.code, 9);
 });
 
-test('should override env-file', onlyWithAmaroAndNodeOptions, async () => {
+test('should not override env-file', onlyWithAmaroAndNodeOptions, async () => {
   const result = await spawnPromisified(process.execPath, [
     '--no-warnings',
     `--experimental-config-file=${fixtures.path('rc/strip-types.json')}`,
     '--env-file', fixtures.path('dotenv/node-options-no-tranform.env'),
     fixtures.path('typescript/ts/test-typescript.ts'),
   ]);
-  assert.strictEqual(result.stderr, '');
-  assert.match(result.stdout, /Hello, TypeScript!/);
-  assert.strictEqual(result.code, 0);
+  assert.match(result.stderr, /SyntaxError/);
+  assert.strictEqual(result.stdout, '');
+  assert.strictEqual(result.code, 1);
 });
 
 test('should not override NODE_OPTIONS', onlyWithAmaro, async () => {

Original file line number	Diff line number	Diff line change
`@@ -870,6 +870,7 @@ static ExitCode InitializeNodeWithArgsInternal(`
`870`	`870`	`HandleEnvOptions(per_process::cli_options->per_isolate->per_env);`
`871`	`871`
`872`	`872`	`std::string node_options;`
	`873`	`+ std::string node_options_from_dotenv;`
`873`	`874`	`auto env_files = node::Dotenv::GetDataFromArgs(*argv);`
`874`	`875`
`875`	`876`	`if (!env_files.empty()) {`
`@@ -896,7 +897,8 @@ static ExitCode InitializeNodeWithArgsInternal(`
`896`	`897`	`}`
`897`	`898`	`}`
`898`	`899`
`899`		`- per_process::dotenv_file.AssignNodeOptionsIfAvailable(&node_options);`
	`900`	`+ per_process::dotenv_file.AssignNodeOptionsIfAvailable(`
	`901`	`+ &node_options_from_dotenv);`
`900`	`902`	`}`
`901`	`903`
`902`	`904`	`std::string node_options_from_config;`
`@@ -932,9 +934,10 @@ static ExitCode InitializeNodeWithArgsInternal(`
`932`	`934`	`errors->emplace_back("The number of NODE_OPTIONS doesn't match "`
`933`	`935`	`"the number of flags in the config file");`
`934`	`936`	`}`
`935`		`- node_options += node_options_from_config;`
`936`	`937`	`}`
`937`	`938`
	`939`	`+ node_options = node_options_from_config + node_options_from_dotenv;`
	`940`	`+`
`938`	`941`	`#if !defined(NODE_WITHOUT_NODE_OPTIONS)`
`939`	`942`	`bool should_parse_node_options =`
`940`	`943`	`!(flags & ProcessInitializationFlags::kDisableNodeOptionsEnv);`
Original file line number	Diff line number	Diff line change
`@@ -356,7 +356,7 @@ void Dotenv::AssignNodeOptionsIfAvailable(std::string* node_options) const {`
`356`	`356`	`auto match = store_.find("NODE_OPTIONS");`
`357`	`357`
`358`	`358`	`if (match != store_.end()) {`
`359`		`- *node_options = match->second;`
	`359`	`+ *node_options = " " + match->second;`
`360`	`360`	`}`
`361`	`361`	`}`
`362`	`362`