src: add config file support #57016

marco-ippolito · 2025-02-12T18:19:53Z

Introducing node.json

node --experimental-config-file=noderc.json file.js

Why a config file?

With the introduction of test runner, sea, and other feature that require a lot of flags, a json config flag would improve by a lot the developer experience and increase adoption.
Example:

node --experimental-config-file=noderc.json --test --experimental-test-coverage

{
 "test-coverage-lines": 80,
 "test-coverage-branches": 60
}

Current solutions

CLI Flags
NODE_OPTIONS
--env-file with NODE_OPTIONS

All of these solutions dont have a good developer experience.

Why JSON?

Simply because we already support json parsing (simdjson) and its kinda the default in the js ecosystem.

Do we have to support all the configurations possible?

NO

Not all flag need to be supported by the config file, and not all flags CAN be supported.
The config file will only support flags that can be passed through NODE_OPTIONS:
https://nodejs.org/api/cli.html#node_optionsoptions

How does it work?

This is an early development, it work similarly to the --env-file flag. It will parse the provided file with --experimental-config-file and add to NODE_OPTIONS the recognized flags. Unrecognized flags will be ignored.

Versioning

json_schema!
When we release a new version, we also release a json schema file.

{
  "$schema": "https://nodejs.org/dist/v20.18.3/docs/node_config_json_schema.json",
}

The users can has autocompletion and validation of their config file specific to the version they are using.
Since the config file mirrors the features that the current version has, it would be impossible to provide semver major backwards compatibility (immagine a feature gets removed we also have to remove it from the config file).

Examples in the ecosystem

Security

Just like .env files, Node.js entrusts the user to provide a secure and valid configuration.

@nodejs/tsc for visibility since its a big feature

nodejs-github-bot · 2025-02-12T18:20:00Z

Review requested:

@nodejs/gyp
@nodejs/startup

anonrig · 2025-02-12T19:30:31Z

I took a somewhat similar approach last year. Happy to talk in private if you need any help. Ref: anonrig#4

src/node_rc.cc

AugustinMauroy · 2025-02-13T20:31:04Z

Should this configuration file include experimental options?
I don't think so, it should just allow config to be used from feature mark to stable.

AugustinMauroy · 2025-02-13T20:51:39Z

And if this configuration file could support the version of node. It could issue a warning if the wrong version is used for the project.
But that would require node to be able to resolve semver ranges.
And I think that would really add a degree of complexity to the file.

marco-ippolito · 2025-02-13T22:52:57Z

I don't see the downside of supporting experimental features. Users can validate with the json schema we provide for the version they are using (you can read in the docs how)

AugustinMauroy · 2025-02-14T08:38:07Z

I think that enabling feature experimental support will increase their adoption, and so in the event of a breaking change, it will impact more users.

codecov · 2025-02-16T13:17:37Z

Codecov Report

Attention: Patch coverage is 72.48062% with 71 lines in your changes missing coverage. Please review.

Project coverage is 90.35%. Comparing base (3b0fce1) to head (a7ee706).
Report is 572 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_config_file.cc	63.02%	33 Missing and 11 partials ⚠️
src/node_options.cc	62.50%	14 Missing and 10 partials ⚠️
src/node.cc	83.33%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57016      +/-   ##
==========================================
- Coverage   90.38%   90.35%   -0.03%     
==========================================
  Files         628      629       +1     
  Lines      184007   184265     +258     
  Branches    35952    36008      +56     
==========================================
+ Hits       166314   166499     +185     
- Misses      10869    10907      +38     
- Partials     6824     6859      +35

Files with missing lines	Coverage Δ
lib/internal/options.js	`100.00% <100.00%> (ø)`
lib/internal/process/pre_execution.js	`93.31% <100.00%> (+1.65%)`	⬆️
src/node_errors.h	`85.00% <ø> (ø)`
src/node_options.h	`98.32% <ø> (ø)`
src/node.cc	`73.96% <83.33%> (+0.38%)`	⬆️
src/node_options.cc	`85.32% <62.50%> (-2.05%)`	⬇️
src/node_config_file.cc	`63.02% <63.02%> (ø)`

... and 21 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jasnell · 2025-02-16T14:51:18Z

Historically I've been fairly anti-config file but I actually think I've come around to the idea. I do think, however, that we need to be careful about making things too confusing for users with some options being passed as command line flags, others being passed as environment variables, and now others possibly being passed by config file. Ideally these mechanisms would integrate with each other such that we can add a configuration option once and it just works (much like we can do today with adding a command line flag and indicate whether it can be used in NODE_OPTIONS or not). It would even be ideal for us to either be able to add an option to the JSON schema and automatically have the code generated in the runtime to support the option or add the option programmatically and provide a way for node.js to generate the json schema dynamically from that. Either way, I've come around to supporting moving in this direction (even if while kicking and screaming).

src/node_rc.cc

jasnell · 2025-02-16T15:13:29Z

src/node_rc.cc

+namespace node {
+
+ConfigReader::ParseResult ConfigReader::ParseExperimentalObject(
+    simdjson::ondemand::object* experimental_object,


@lemire ... I'm curious, does simdjson support jsonc? (JSON with comments). Would it be difficult to add support for jsonc if not? If we're going to use json as a configuration format, then supporting comments is ideal. (note that both deno and bun support comments in their respective formats)

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

Notable changes: deps: * update timezone to 2025b (Node.js GitHub Bot) #57857 doc: * add dario-piotrowicz to collaborators (Dario Piotrowicz) #58102 * (SEMVER-MINOR) graduate multiple experimental apis (James M Snell) #57765 esm: * (SEMVER-MINOR) graduate import.meta properties (James M Snell) #58011 * (SEMVER-MINOR) support top-level Wasm without package type (Guy Bedford) #57610 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.columns() (Colin Ihrig) #57490 src: * (SEMVER-MINOR) set default config as `node.config.json` (Marco Ippolito) #57171 * (SEMVER-MINOR) create `THROW_ERR_OPTIONS_BEFORE_BOOTSTRAPPING` (Marco Ippolito) #57016 * (SEMVER-MINOR) add config file support (Marco Ippolito) #57016 * (SEMVER-MINOR) add ExecutionAsyncId getter for any Context (Attila Szegedi) #57820 stream: * (SEMVER-MINOR) preserve AsyncLocalStorage context in finished() (Gürgün Dayıoğlu) #57865 util: * (SEMVER-MINOR) add `types.isFloat16Array()` (Livia Medeiros) #57879 worker: * (SEMVER-MINOR) add worker.getHeapStatistics() (Matteo Collina) #57888 PR-URL: #58388

PR-URL: #57016 Backport-PR-URL: #57958 Refs: #53787 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Paolo Insogna <[email protected]>

`parallel/test-config-json-schema` compares to a generated fixture that assumes that Node.js was built with default configuration settings. Skip the test if non-default quic is enabled (`configure --with-quic`). Refs: #57016 Refs: #57142 PR-URL: #57225 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Yagiz Nizipli <[email protected]>

Notable changes: deps: * update timezone to 2025b (Node.js GitHub Bot) #57857 doc: * add dario-piotrowicz to collaborators (Dario Piotrowicz) #58102 * (SEMVER-MINOR) graduate multiple experimental apis (James M Snell) #57765 esm: * (SEMVER-MINOR) graduate import.meta properties (James M Snell) #58011 * (SEMVER-MINOR) support top-level Wasm without package type (Guy Bedford) #57610 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.columns() (Colin Ihrig) #57490 src: * (SEMVER-MINOR) set default config as `node.config.json` (Marco Ippolito) #57171 * (SEMVER-MINOR) create `THROW_ERR_OPTIONS_BEFORE_BOOTSTRAPPING` (Marco Ippolito) #57016 * (SEMVER-MINOR) add config file support (Marco Ippolito) #57016 * (SEMVER-MINOR) add ExecutionAsyncId getter for any Context (Attila Szegedi) #57820 stream: * (SEMVER-MINOR) preserve AsyncLocalStorage context in finished() (Gürgün Dayıoğlu) #57865 util: * (SEMVER-MINOR) add `types.isFloat16Array()` (Livia Medeiros) #57879 worker: * (SEMVER-MINOR) add worker.getHeapStatistics() (Matteo Collina) #57888 PR-URL: TODO

Notable changes: deps: * update timezone to 2025b (Node.js GitHub Bot) #57857 doc: * add dario-piotrowicz to collaborators (Dario Piotrowicz) #58102 * (SEMVER-MINOR) graduate multiple experimental apis (James M Snell) #57765 esm: * (SEMVER-MINOR) graduate import.meta properties (James M Snell) #58011 * (SEMVER-MINOR) support top-level Wasm without package type (Guy Bedford) #57610 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.columns() (Colin Ihrig) #57490 src: * (SEMVER-MINOR) set default config as `node.config.json` (Marco Ippolito) #57171 * (SEMVER-MINOR) create `THROW_ERR_OPTIONS_BEFORE_BOOTSTRAPPING` (Marco Ippolito) #57016 * (SEMVER-MINOR) add config file support (Marco Ippolito) #57016 * (SEMVER-MINOR) add ExecutionAsyncId getter for any Context (Attila Szegedi) #57820 stream: * (SEMVER-MINOR) preserve AsyncLocalStorage context in finished() (Gürgün Dayıoğlu) #57865 util: * (SEMVER-MINOR) add `types.isFloat16Array()` (Livia Medeiros) #57879 worker: * (SEMVER-MINOR) add worker.getHeapStatistics() (Matteo Collina) #57888 PR-URL: #58388

Notable changes: deps: * update timezone to 2025b (Node.js GitHub Bot) nodejs#57857 doc: * add dario-piotrowicz to collaborators (Dario Piotrowicz) nodejs#58102 * (SEMVER-MINOR) graduate multiple experimental apis (James M Snell) nodejs#57765 esm: * (SEMVER-MINOR) graduate import.meta properties (James M Snell) nodejs#58011 * (SEMVER-MINOR) support top-level Wasm without package type (Guy Bedford) nodejs#57610 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.columns() (Colin Ihrig) nodejs#57490 src: * (SEMVER-MINOR) set default config as `node.config.json` (Marco Ippolito) nodejs#57171 * (SEMVER-MINOR) create `THROW_ERR_OPTIONS_BEFORE_BOOTSTRAPPING` (Marco Ippolito) nodejs#57016 * (SEMVER-MINOR) add config file support (Marco Ippolito) nodejs#57016 * (SEMVER-MINOR) add ExecutionAsyncId getter for any Context (Attila Szegedi) nodejs#57820 stream: * (SEMVER-MINOR) preserve AsyncLocalStorage context in finished() (Gürgün Dayıoğlu) nodejs#57865 util: * (SEMVER-MINOR) add `types.isFloat16Array()` (Livia Medeiros) nodejs#57879 worker: * (SEMVER-MINOR) add worker.getHeapStatistics() (Matteo Collina) nodejs#57888 PR-URL: nodejs#58388

Notable changes: deps: * update timezone to 2025b (Node.js GitHub Bot) #57857 doc: * add dario-piotrowicz to collaborators (Dario Piotrowicz) #58102 * (SEMVER-MINOR) graduate multiple experimental apis (James M Snell) #57765 esm: * (SEMVER-MINOR) graduate import.meta properties (James M Snell) #58011 * (SEMVER-MINOR) support top-level Wasm without package type (Guy Bedford) #57610 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.columns() (Colin Ihrig) #57490 src: * (SEMVER-MINOR) set default config as `node.config.json` (Marco Ippolito) #57171 * (SEMVER-MINOR) create `THROW_ERR_OPTIONS_BEFORE_BOOTSTRAPPING` (Marco Ippolito) #57016 * (SEMVER-MINOR) add config file support (Marco Ippolito) #57016 * (SEMVER-MINOR) add ExecutionAsyncId getter for any Context (Attila Szegedi) #57820 stream: * (SEMVER-MINOR) preserve AsyncLocalStorage context in finished() (Gürgün Dayıoğlu) #57865 util: * (SEMVER-MINOR) add `types.isFloat16Array()` (Livia Medeiros) #57879 worker: * (SEMVER-MINOR) add worker.getHeapStatistics() (Matteo Collina) #57888 PR-URL: #58388

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 Feb 12, 2025

marco-ippolito requested review from anonrig and joyeecheung February 12, 2025 18:23

marco-ippolito force-pushed the feat/config-file branch from 5d7ff50 to 3f46529 Compare February 12, 2025 19:32

richardlau added the semver-minor PRs that contain new features and should be released in the next minor version. label Feb 12, 2025

marco-ippolito force-pushed the feat/config-file branch 2 times, most recently from 272828d to 497298b Compare February 12, 2025 21:53

anonrig reviewed Feb 12, 2025

View reviewed changes