src: set default config as node.config.json

marco-ippolito · targos · commit 274c18a36571 · 2025-03-11T19:38:12.000+01:00
PR-URL: #57171 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
diff --git a/Makefile b/Makefile
@@ -809,7 +809,7 @@ doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation wit
 
 out/doc:
 	mkdir -p $@
-	cp doc/node_config_json_schema.json $@
+	cp doc/node-config-schema.json $@
 
 # If it's a source tarball, doc/api already contains the generated docs.
 # Just copy everything under doc/api over.
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -919,29 +919,30 @@ flows within the application. As such, it is presently recommended to be sure
 your application behaviour is unaffected by this change before using it in
 production.
 
-### `--experimental-config-file`
+### `--experimental-config-file=config`
 
 <!-- YAML
 added: REPLACEME
 -->
 
 > Stability: 1.0 - Early development
 
-Use this flag to specify a configuration file that will be loaded and parsed
-before the application starts.
+If present, Node.js will look for a
+configuration file at the specified path.
 Node.js will read the configuration file and apply the settings.
 The configuration file should be a JSON file
 with the following structure:
 
+> \[!NOTE]
+> Replace `vX.Y.Z` in the `$schema` with the version of Node.js you are using.
+
 ```json
 {
-  "$schema": "https://nodejs.org/dist/REPLACEME/docs/node_config_json_schema.json",
+  "$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
   "nodeOptions": {
-    "experimental-transform-types": true,
     "import": [
-      "amaro/transform"
+      "amaro/strip"
     ],
-    "disable-warning": "ExperimentalWarning",
     "watch-path": "src",
     "watch-preserve-output": true
   }
@@ -952,7 +953,7 @@ In the `nodeOptions` field, only flags that are allowed in [`NODE_OPTIONS`][] ar
 No-op flags are not supported.
 Not all V8 flags are currently supported.
 
-It is possible to use the [official JSON schema](../node_config_json_schema.json)
+It is possible to use the [official JSON schema](../node-config-schema.json)
 to validate the configuration file, which may vary depending on the Node.js version.
 Each key in the configuration file corresponds to a flag that can be passed
 as a command-line argument. The value of the key is the value that would be
@@ -962,7 +963,7 @@ For example, the configuration file above is equivalent to
 the following command-line arguments:
 
 ```bash
-node --experimental-transform-types --import amaro/transform --disable-warning=ExperimentalWarning --watch-path=src --watch-preserve-output
+node --import amaro/strip --watch-path=src --watch-preserve-output
 ```
 
 The priority in configuration is as follows:
@@ -984,6 +985,18 @@ unknown keys or keys that cannot used in `NODE_OPTIONS`.
 Node.js will not sanitize or perform validation on the user-provided configuration,
 so **NEVER** use untrusted configuration files.
 
+### `--experimental-default-config-file`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+If the `--experimental-default-config-file` flag is present, Node.js will look for a
+`node.config.json` file in the current working directory and load it as a
+as configuration file.
+
 ### `--experimental-eventsource`
 
 <!-- YAML
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
diff --git a/doc/node.1 b/doc/node.1
@@ -167,7 +167,10 @@ Interpret the entry point as a URL.
 Enable experimental addon module support.
 .
 .It Fl -experimental-config-file
-Enable support for experimental config file
+Specifies the configuration file to load.
+.
+.It Fl -experimental-default-config-file
+Enable support for automatically loading node.config.json.
 .
 .It Fl -experimental-import-meta-resolve
 Enable experimental ES modules support for import.meta.resolve().
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -315,7 +315,8 @@ function setupSQLite() {
 }
 
 function initializeConfigFileSupport() {
-  if (getOptionValue('--experimental-config-file')) {
+  if (getOptionValue('--experimental-default-config-file') ||
+      getOptionValue('--experimental-config-file')) {
     emitExperimentalWarning('--experimental-config-file');
   }
 }
diff --git a/src/node_config_file.cc b/src/node_config_file.cc
@@ -8,22 +8,32 @@ namespace node {
 
 std::optional<std::string_view> ConfigReader::GetDataFromArgs(
     const std::vector<std::string>& args) {
-  constexpr std::string_view flag = "--experimental-config-file";
+  constexpr std::string_view flag_path = "--experimental-config-file";
+  constexpr std::string_view default_file =
+      "--experimental-default-config-file";
+
+  bool has_default_config_file = false;
 
   for (auto it = args.begin(); it != args.end(); ++it) {
-    if (*it == flag) {
+    if (*it == flag_path) {
       // Case: "--experimental-config-file foo"
       if (auto next = std::next(it); next != args.end()) {
         return *next;
       }
-    } else if (it->starts_with(flag)) {
+    } else if (it->starts_with(flag_path)) {
       // Case: "--experimental-config-file=foo"
-      if (it->size() > flag.size() && (*it)[flag.size()] == '=') {
-        return it->substr(flag.size() + 1);
+      if (it->size() > flag_path.size() && (*it)[flag_path.size()] == '=') {
+        return it->substr(flag_path.size() + 1);
       }
+    } else if (*it == default_file || it->starts_with(default_file)) {
+      has_default_config_file = true;
     }
   }
 
+  if (has_default_config_file) {
+    return "node.config.json";
+  }
+
   return std::nullopt;
 }
 
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -685,7 +685,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   Implies("--env-file-if-exists", "[has_env_file_string]");
   AddOption("--experimental-config-file",
             "set config file from supplied file",
-            &EnvironmentOptions::experimental_config_file);
+            &EnvironmentOptions::experimental_config_file_path);
+  AddOption("--experimental-default-config-file",
+            "set config file from default config file",
+            &EnvironmentOptions::experimental_default_config_file);
   AddOption("--test",
             "launch test runner on startup",
             &EnvironmentOptions::test_runner);
diff --git a/src/node_options.h b/src/node_options.h
@@ -258,7 +258,8 @@ class EnvironmentOptions : public Options {
 
   bool report_exclude_env = false;
   bool report_exclude_network = false;
-  std::string experimental_config_file;
+  std::string experimental_config_file_path;
+  bool experimental_default_config_file = false;
 
   inline DebugOptions* get_debug_options() { return &debug_options_; }
   inline const DebugOptions& debug_options() const { return debug_options_; }
diff --git a/test/fixtures/rc/default/node.config.json b/test/fixtures/rc/default/node.config.json
@@ -0,0 +1,5 @@
+{
+  "nodeOptions": {
+    "max-http-header-size": 10
+  }
+}
diff --git a/test/fixtures/rc/default/override.json b/test/fixtures/rc/default/override.json
@@ -0,0 +1,5 @@
+{
+  "nodeOptions": {
+    "max-http-header-size": 20
+  }
+}
diff --git a/test/fixtures/rc/non-readable/node.config.json b/test/fixtures/rc/non-readable/node.config.json
@@ -0,0 +1,5 @@
+{
+    "nodeOptions": {
+        "max-http-header-size": 10
+    }
+}
diff --git a/test/parallel/test-config-file.js b/test/parallel/test-config-file.js
@@ -4,6 +4,8 @@ const { spawnPromisified } = require('../common');
 const fixtures = require('../common/fixtures');
 const { match, strictEqual } = require('node:assert');
 const { test } = require('node:test');
+const { chmodSync, constants } = require('node:fs');
+const common = require('../common');
 
 test('should handle non existing json', async () => {
   const result = await spawnPromisified(process.execPath, [
@@ -304,3 +306,47 @@ test('broken value in node_options', async () => {
   strictEqual(result.stdout, '');
   strictEqual(result.code, 9);
 });
+
+test('should use node.config.json as default', async () => {
+  const result = await spawnPromisified(process.execPath, [
+    '--no-warnings',
+    '--experimental-default-config-file',
+    '-p', 'http.maxHeaderSize',
+  ], {
+    cwd: fixtures.path('rc/default'),
+  });
+  strictEqual(result.stderr, '');
+  strictEqual(result.stdout, '10\n');
+  strictEqual(result.code, 0);
+});
+
+test('should override node.config.json when specificied', async () => {
+  const result = await spawnPromisified(process.execPath, [
+    '--no-warnings',
+    '--experimental-default-config-file',
+    '--experimental-config-file',
+    fixtures.path('rc/default/override.json'),
+    '-p', 'http.maxHeaderSize',
+  ], {
+    cwd: fixtures.path('rc/default'),
+  });
+  strictEqual(result.stderr, '');
+  strictEqual(result.stdout, '20\n');
+  strictEqual(result.code, 0);
+});
+// Skip on windows because it doesn't support chmod changing read permissions
+test('should throw an error when the file is non readable', { skip: common.isWindows }, async () => {
+  chmodSync(fixtures.path('rc/non-readable/node.config.json'), constants.O_RDONLY);
+  const result = await spawnPromisified(process.execPath, [
+    '--no-warnings',
+    '--experimental-default-config-file',
+    '-p', 'http.maxHeaderSize',
+  ], {
+    cwd: fixtures.path('rc/non-readable'),
+  });
+  match(result.stderr, /Cannot read configuration from node\.config\.json: permission denied/);
+  strictEqual(result.stdout, '');
+  strictEqual(result.code, 9);
+  chmodSync(fixtures.path('rc/non-readable/node.config.json'),
+            constants.S_IRWXU | constants.S_IRWXG | constants.S_IRWXO);
+});
diff --git a/test/parallel/test-config-json-schema.js b/test/parallel/test-config-json-schema.js
@@ -24,7 +24,7 @@ if (!common.hasIntl) {
 const {
   generateConfigJsonSchema,
 } = require('internal/options');
-const schemaInDoc = require('../../doc/node_config_json_schema.json');
+const schemaInDoc = require('../../doc/node-config-schema.json');
 const assert = require('assert');
 
 const schema = generateConfigJsonSchema();
@@ -35,6 +35,6 @@ const schema = generateConfigJsonSchema();
 // current JSON schema.
 // To regenerate the JSON schema, run:
 // out/Release/node --expose-internals tools/doc/generate-json-schema.mjs
-// And then run make doc to update the out/doc/node_config_json_schema.json file.
+// And then run make doc to update the out/doc/node-config-schema.json file.
 assert.strictEqual(JSON.stringify(schema), JSON.stringify(schemaInDoc), 'JSON schema is outdated.' +
   'Run `out/Release/node --expose-internals tools/doc/generate-json-schema.mjs` to update it.');
diff --git a/tools/doc/generate-json-schema.mjs b/tools/doc/generate-json-schema.mjs
@@ -4,4 +4,4 @@ import internal from 'internal/options';
 import { writeFileSync } from 'fs';
 
 const schema = internal.generateConfigJsonSchema();
-writeFileSync('doc/node_config_json_schema.json', `${JSON.stringify(schema, null, 2)}\n`);
+writeFileSync('doc/node-config-schema.json', `${JSON.stringify(schema, null, 2)}\n`);

Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,10 @@ Interpret the entry point as a URL.`
`167`	`167`	`Enable experimental addon module support.`
`168`	`168`	`.`
`169`	`169`	`.It Fl -experimental-config-file`
`170`		`-Enable support for experimental config file`
	`170`	`+Specifies the configuration file to load.`
	`171`	`+.`
	`172`	`+.It Fl -experimental-default-config-file`
	`173`	`+Enable support for automatically loading node.config.json.`
`171`	`174`	`.`
`172`	`175`	`.It Fl -experimental-import-meta-resolve`
`173`	`176`	`Enable experimental ES modules support for import.meta.resolve().`
Original file line number	Diff line number	Diff line change
`@@ -315,7 +315,8 @@ function setupSQLite() {`
`315`	`315`	`}`
`316`	`316`
`317`	`317`	`function initializeConfigFileSupport() {`
`318`		`- if (getOptionValue('--experimental-config-file')) {`
	`318`	`+ if (getOptionValue('--experimental-default-config-file') \|\|`
	`319`	`+ getOptionValue('--experimental-config-file')) {`
`319`	`320`	`emitExperimentalWarning('--experimental-config-file');`
`320`	`321`	`}`
`321`	`322`	`}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +  "nodeOptions": {
 +    "max-http-header-size": 10
 +  }
 +}