src: swap dotenv and config file parsing order

marco-ippolito · aduh95 · commit 99bb02fd9e82 · 2026-05-07T15:41:50.000+02:00
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
@@ -1020,12 +1020,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
@@ -879,6 +879,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()) {
@@ -905,7 +906,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;
@@ -935,9 +937,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
@@ -345,7 +345,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
@@ -92,17 +92,17 @@ 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/transform-types.json'),
     '--env-file', fixtures.path('dotenv/node-options-no-tranform.env'),
     fixtures.path('typescript/ts/transformation/test-enum.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
`@@ -879,6 +879,7 @@ static ExitCode InitializeNodeWithArgsInternal(`
`879`	`879`	`HandleEnvOptions(per_process::cli_options->per_isolate->per_env);`
`880`	`880`
`881`	`881`	`std::string node_options;`
	`882`	`+ std::string node_options_from_dotenv;`
`882`	`883`	`auto env_files = node::Dotenv::GetDataFromArgs(*argv);`
`883`	`884`
`884`	`885`	`if (!env_files.empty()) {`
`@@ -905,7 +906,8 @@ static ExitCode InitializeNodeWithArgsInternal(`
`905`	`906`	`}`
`906`	`907`	`}`
`907`	`908`
`908`		`- per_process::dotenv_file.AssignNodeOptionsIfAvailable(&node_options);`
	`909`	`+ per_process::dotenv_file.AssignNodeOptionsIfAvailable(`
	`910`	`+ &node_options_from_dotenv);`
`909`	`911`	`}`
`910`	`912`
`911`	`913`	`std::string node_options_from_config;`
`@@ -935,9 +937,10 @@ static ExitCode InitializeNodeWithArgsInternal(`
`935`	`937`	`errors->emplace_back("The number of NODE_OPTIONS doesn't match "`
`936`	`938`	`"the number of flags in the config file");`
`937`	`939`	`}`
`938`		`- node_options += node_options_from_config;`
`939`	`940`	`}`
`940`	`941`
	`942`	`+ node_options = node_options_from_config + node_options_from_dotenv;`
	`943`	`+`
`941`	`944`	`#if !defined(NODE_WITHOUT_NODE_OPTIONS)`
`942`	`945`	`bool should_parse_node_options =`
`943`	`946`	`!(flags & ProcessInitializationFlags::kDisableNodeOptionsEnv);`
Original file line number	Diff line number	Diff line change
`@@ -345,7 +345,7 @@ void Dotenv::AssignNodeOptionsIfAvailable(std::string* node_options) const {`
`345`	`345`	`auto match = store_.find("NODE_OPTIONS");`
`346`	`346`
`347`	`347`	`if (match != store_.end()) {`
`348`		`- *node_options = match->second;`
	`348`	`+ *node_options = " " + match->second;`
`349`	`349`	`}`
`350`	`350`	`}`
`351`	`351`