Skip to content

Commit cd86506

Browse files
marco-ippolitorichardlau
marco-ippolito
authored and
richardlau
committed
src: mark config file as stable
Signed-off-by: Marco Ippolito <[email protected]> PR-URL: #66431 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Edy Silva <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Pietro Marchini <[email protected]>
1 parent 63c20ee commit cd86506

23 files changed

Lines changed: 428 additions & 418 deletions

‎doc/api/cli.md‎

Lines changed: 157 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -747,6 +747,163 @@ For example, to run a module with "development" resolutions:
747747
node -C development app.js
748748
```
749749

750+
### `--config-file=path`, `--config-file`
751+
752+
<!-- YAML
753+
added:
754+
- v23.10.0
755+
- v22.16.0
756+
changes:
757+
- version: REPLACEME
758+
pr-url: https://github.com/nodejs/node/pull/66431
759+
description: This flag was renamed from `--experimental-config-file` to
760+
`--config-file` and is now stable. `--experimental-config-file`
761+
and `--experimental-default-config-file` are kept as aliases.
762+
- version: v26.7.0
763+
pr-url: https://github.com/nodejs/node/pull/64516
764+
description: Marked as release candidate.
765+
-->
766+
767+
If present, Node.js will look for a configuration file at the specified path.
768+
If the path is not specified, Node.js will look for a `node.config.json` file
769+
in the current working directory.
770+
To specify a custom path, use the `--config-file=path` form.
771+
The space-separated `--config-file path` form is not supported.
772+
Node.js will read the configuration file and apply the settings. The
773+
configuration file should be a JSON file with the following structure. `vX.Y.Z`
774+
in the `$schema` must be replaced with the version of Node.js you are using or
775+
`latest-vX.x` for the latest version of that major release line.
776+
777+
```json
778+
{
779+
"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
780+
"nodeOptions": {
781+
"import": [
782+
"amaro/strip"
783+
],
784+
"watch-path": "src",
785+
"watch-preserve-output": true
786+
},
787+
"test": {
788+
"test-isolation": "process"
789+
},
790+
"watch": {
791+
"watch-preserve-output": true
792+
}
793+
}
794+
```
795+
796+
The configuration file supports namespace-specific options:
797+
798+
* The `nodeOptions` field contains CLI flags that are allowed in [`NODE_OPTIONS`][].
799+
800+
* Namespace fields like `test`, `watch`, and `permission` contain configuration specific to that subsystem.
801+
802+
The configuration file can target a specific Node.js major version with
803+
`nodeVersion`:
804+
805+
```json
806+
{
807+
"nodeVersion": 25,
808+
"nodeOptions": {
809+
"watch-path": "src"
810+
}
811+
}
812+
```
813+
814+
To keep multiple version-specific configurations in the same file, use the
815+
`configs` array. Node.js will use the first entry whose `nodeVersion` matches
816+
the current Node.js major version:
817+
818+
```json
819+
{
820+
"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
821+
"configs": [
822+
{
823+
"nodeVersion": 25,
824+
"config": {
825+
"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
826+
"nodeOptions": {
827+
"watch-path": "src"
828+
}
829+
}
830+
}
831+
]
832+
}
833+
```
834+
835+
When `configs` is used, the top level may only contain `$schema` and
836+
`configs`. Each `configs` item must define an integer `nodeVersion` and an
837+
object `config`. A single top-level config does not require `nodeVersion`, but
838+
if present it must match the current Node.js major version.
839+
840+
When a namespace is present in the
841+
configuration file, Node.js automatically enables the corresponding flag
842+
(e.g., `--test`, `--watch`, `--permission`). This allows you to configure
843+
subsystem-specific options without explicitly passing the flag on the command line.
844+
845+
For example:
846+
847+
```json
848+
{
849+
"test": {
850+
"test-isolation": "process"
851+
}
852+
}
853+
```
854+
855+
is equivalent to:
856+
857+
```bash
858+
node --test --test-isolation=process
859+
```
860+
861+
To disable the automatic flag while still using namespace options, you can
862+
explicitly set the flag to `false` within the namespace:
863+
864+
```json
865+
{
866+
"test": {
867+
"test": false,
868+
"test-isolation": "process"
869+
}
870+
}
871+
```
872+
873+
No-op flags are not supported.
874+
Not all V8 flags are currently supported.
875+
876+
It is possible to use the [official JSON schema](../node-config-schema.json)
877+
to validate the configuration file, which may vary depending on the Node.js version.
878+
Each key in the configuration file corresponds to a flag that can be passed
879+
as a command-line argument. The value of the key is the value that would be
880+
passed to the flag.
881+
882+
For example, the configuration file above is equivalent to
883+
the following command-line arguments:
884+
885+
```bash
886+
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
887+
```
888+
889+
The priority in configuration is as follows:
890+
891+
1. NODE\_OPTIONS and command-line options
892+
2. Dotenv NODE\_OPTIONS
893+
3. Configuration file
894+
895+
Values in the configuration file will not override the values in the environment
896+
variables, command-line options, or the `NODE_OPTIONS` env file parsed by the
897+
`--env-file` flag.
898+
899+
Keys cannot be duplicated within the same or different namespaces.
900+
901+
The configuration parser will throw an error if the configuration file contains
902+
unknown keys or keys that cannot be used in a namespace.
903+
904+
Node.js will not sanitize or perform validation on the user-provided configuration,
905+
so **NEVER** use untrusted configuration files.
906+
750907
### `--cpu-prof`
751908

752909
<!-- YAML
@@ -1223,177 +1380,6 @@ added: v26.9.0
12231380
12241381
Enable the experimental `node:bench` module and command-line benchmark runner.
12251382

1226-
### `--experimental-config-file=path`, `--experimental-config-file`
1227-
1228-
<!-- YAML
1229-
added:
1230-
- v23.10.0
1231-
- v22.16.0
1232-
changes:
1233-
- version: v26.7.0
1234-
pr-url: https://github.com/nodejs/node/pull/64516
1235-
description: Marked as release candidate.
1236-
-->
1237-
1238-
> Stability: 1.2 - Release candidate
1239-
1240-
If present, Node.js will look for a configuration file at the specified path.
1241-
If the path is not specified, Node.js will look for a `node.config.json` file
1242-
in the current working directory.
1243-
To specify a custom path, use the `--experimental-config-file=path` form.
1244-
The space-separated `--experimental-config-file path` form is not supported.
1245-
The alias `--experimental-default-config-file` is equivalent to
1246-
`--experimental-config-file` without an argument.
1247-
Node.js will read the configuration file and apply the settings. The
1248-
configuration file should be a JSON file with the following structure. `vX.Y.Z`
1249-
in the `$schema` must be replaced with the version of Node.js you are using or
1250-
`latest-vX.x` for the latest version of that major release line.
1251-
1252-
```json
1253-
{
1254-
"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
1255-
"nodeOptions": {
1256-
"import": [
1257-
"amaro/strip"
1258-
],
1259-
"watch-path": "src",
1260-
"watch-preserve-output": true
1261-
},
1262-
"test": {
1263-
"test-isolation": "process"
1264-
},
1265-
"watch": {
1266-
"watch-preserve-output": true
1267-
}
1268-
}
1269-
```
1270-
1271-
The configuration file supports namespace-specific options:
1272-
1273-
* The `nodeOptions` field contains CLI flags that are allowed in [`NODE_OPTIONS`][].
1274-
1275-
* Namespace fields like `test`, `watch`, and `permission` contain configuration specific to that subsystem.
1276-
1277-
The configuration file can target a specific Node.js major version with
1278-
`nodeVersion`:
1279-
1280-
```json
1281-
{
1282-
"nodeVersion": 25,
1283-
"nodeOptions": {
1284-
"watch-path": "src"
1285-
}
1286-
}
1287-
```
1288-
1289-
To keep multiple version-specific configurations in the same file, use the
1290-
`configs` array. Node.js will use the first entry whose `nodeVersion` matches
1291-
the current Node.js major version:
1292-
1293-
```json
1294-
{
1295-
"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
1296-
"configs": [
1297-
{
1298-
"nodeVersion": 25,
1299-
"config": {
1300-
"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
1301-
"nodeOptions": {
1302-
"watch-path": "src"
1303-
}
1304-
}
1305-
}
1306-
]
1307-
}
1308-
```
1309-
1310-
When `configs` is used, the top level may only contain `$schema` and
1311-
`configs`. Each `configs` item must define an integer `nodeVersion` and an
1312-
object `config`. A single top-level config does not require `nodeVersion`, but
1313-
if present it must match the current Node.js major version.
1314-
1315-
When a namespace is present in the
1316-
configuration file, Node.js automatically enables the corresponding flag
1317-
(e.g., `--test`, `--watch`, `--permission`). This allows you to configure
1318-
subsystem-specific options without explicitly passing the flag on the command line.
1319-
1320-
For example:
1321-
1322-
```json
1323-
{
1324-
"test": {
1325-
"test-isolation": "process"
1326-
}
1327-
}
1328-
```
1329-
1330-
is equivalent to:
1331-
1332-
```bash
1333-
node --test --test-isolation=process
1334-
```
1335-
1336-
To disable the automatic flag while still using namespace options, you can
1337-
explicitly set the flag to `false` within the namespace:
1338-
1339-
```json
1340-
{
1341-
"test": {
1342-
"test": false,
1343-
"test-isolation": "process"
1344-
}
1345-
}
1346-
```
1347-
1348-
No-op flags are not supported.
1349-
Not all V8 flags are currently supported.
1350-
1351-
It is possible to use the [official JSON schema](../node-config-schema.json)
1352-
to validate the configuration file, which may vary depending on the Node.js version.
1353-
Each key in the configuration file corresponds to a flag that can be passed
1354-
as a command-line argument. The value of the key is the value that would be
1355-
passed to the flag.
1356-
1357-
For example, the configuration file above is equivalent to
1358-
the following command-line arguments:
1359-
1360-
```bash
1361-
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
1362-
```
1363-
1364-
The priority in configuration is as follows:
1365-
1366-
1. NODE\_OPTIONS and command-line options
1367-
2. Dotenv NODE\_OPTIONS
1368-
3. Configuration file
1369-
1370-
Values in the configuration file will not override the values in the environment
1371-
variables, command-line options, or the `NODE_OPTIONS` env file parsed by the
1372-
`--env-file` flag.
1373-
1374-
Keys cannot be duplicated within the same or different namespaces.
1375-
1376-
The configuration parser will throw an error if the configuration file contains
1377-
unknown keys or keys that cannot be used in a namespace.
1378-
1379-
Node.js will not sanitize or perform validation on the user-provided configuration,
1380-
so **NEVER** use untrusted configuration files.
1381-
1382-
### `--experimental-default-config-file`
1383-
1384-
<!-- YAML
1385-
added:
1386-
- v23.10.0
1387-
- v22.16.0
1388-
-->
1389-
1390-
> Stability: 1.0 - Early development
1391-
1392-
This flag is an alias for `--experimental-config-file` without an argument.
1393-
If present, Node.js will look for a
1394-
`node.config.json` file in the current working directory and load it as a
1395-
configuration file.
1396-
13971383
### `--experimental-dtls`
13981384

13991385
<!-- YAML

‎doc/api/permissions.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -269,9 +269,9 @@ both to the top-level `node:fs` functions and to the equivalent
269269
#### Configuration file support
270270

271271
In addition to passing permission flags on the command line, they can also be
272-
declared in a Node.js configuration file when using the experimental
273-
\[`--experimental-config-file`]\[] flag. Permission options must be placed inside
274-
the `permission` top-level object.
272+
declared in a Node.js configuration file when using the [`--config-file`][]
273+
flag. Permission options must be placed inside the `permission` top-level
274+
object.
275275

276276
Example `node.config.json`:
277277

@@ -294,7 +294,7 @@ When the `permission` namespace is present in the configuration file, Node.js
294294
automatically enables the `--permission` flag. Run with:
295295

296296
```console
297-
$ node --experimental-default-config-file app.js
297+
$ node --config-file app.js
298298
```
299299

300300
#### Using the Permission Model with `npx`
@@ -417,6 +417,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
417417
[`--allow-openssl-store`]: cli.md#--allow-openssl-store
418418
[`--allow-wasi`]: cli.md#--allow-wasi
419419
[`--allow-worker`]: cli.md#--allow-worker
420+
[`--config-file`]: cli.md#--config-filepath---config-file
420421
[`--permission-audit`]: cli.md#--permission-audit
421422
[`--permission`]: cli.md#--permission
422423
[`crypto.createPrivateKey()`]: crypto.md#cryptocreateprivatekeykey

‎doc/api/test.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -881,10 +881,9 @@ test runner functionality:
881881
* `--experimental-test-tag-filter` - Filter expressions are validated by the parent
882882
process and re-emitted to child processes
883883
* `--watch` - Watch mode is handled at the parent level
884-
* `--experimental-default-config-file` - Config file loading is handled by the parent
885884
* `--test-reporter` - Reporting is managed by the parent process
886885
* `--test-reporter-destination` - Output destinations are controlled by the parent
887-
* `--experimental-config-file` - Config file paths are managed by the parent
886+
* `--config-file` - Config file paths are managed by the parent
888887
* `--test-randomize` - Randomization is managed by the parent process and
889888
propagated to child processes
890889
* `--test-random-seed` - Randomization seed is managed by the parent process and
@@ -5015,7 +5014,7 @@ test.describe('my suite', (suite) => {
50155014
[`suite()`]: #suitename-options-fn
50165015
[`test()`]: #testname-options-fn
50175016
[code coverage]: #collecting-code-coverage
5018-
[configuration files]: cli.md#--experimental-config-filepath---experimental-config-file
5017+
[configuration files]: cli.md#--config-filepath---config-file
50195018
[describe options]: #describename-options-fn
50205019
[it options]: #testname-options-fn
50215020
[module customization hooks]: module.md#customization-hooks

0 commit comments

Comments
 (0)