Skip to content

Commit c260c9c

Browse files
marco-ippolitomarco-ippolito
committed
src: mark config file as stable
Signed-off-by: Marco Ippolito <marcoippolito54@gmail.com>
1 parent 8bf7793 commit c260c9c

24 files changed

Lines changed: 433 additions & 423 deletions

‎doc/api/cli.md‎

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

802+
### `--config-file=path`, `--config-file`
803+
804+
<!-- YAML
805+
added:
806+
- v23.10.0
807+
- v22.16.0
808+
changes:
809+
- version: REPLACEME
810+
pr-url: https://github.com/nodejs/node/pull/66431
811+
description: This flag was renamed from `--experimental-config-file` to
812+
`--config-file` and is now stable. `--experimental-config-file`
813+
and `--experimental-default-config-file` are kept as aliases.
814+
- version: v26.7.0
815+
pr-url: https://github.com/nodejs/node/pull/64516
816+
description: Marked as release candidate.
817+
-->
818+
819+
If present, Node.js will look for a configuration file at the specified path.
820+
If the path is not specified, Node.js will look for a `node.config.json` file
821+
in the current working directory.
822+
To specify a custom path, use the `--config-file=path` form.
823+
The space-separated `--config-file path` form is not supported.
824+
Node.js will read the configuration file and apply the settings. The
825+
configuration file should be a JSON file with the following structure. `vX.Y.Z`
826+
in the `$schema` must be replaced with the version of Node.js you are using or
827+
`latest-vX.x` for the latest version of that major release line.
828+
829+
```json
830+
{
831+
"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
832+
"nodeOptions": {
833+
"import": [
834+
"amaro/strip"
835+
],
836+
"watch-path": "src",
837+
"watch-preserve-output": true
838+
},
839+
"test": {
840+
"test-isolation": "process"
841+
},
842+
"watch": {
843+
"watch-preserve-output": true
844+
}
845+
}
846+
```
847+
848+
The configuration file supports namespace-specific options:
849+
850+
* The `nodeOptions` field contains CLI flags that are allowed in [`NODE_OPTIONS`][].
851+
852+
* Namespace fields like `test`, `watch`, and `permission` contain configuration specific to that subsystem.
853+
854+
The configuration file can target a specific Node.js major version with
855+
`nodeVersion`:
856+
857+
```json
858+
{
859+
"nodeVersion": 25,
860+
"nodeOptions": {
861+
"watch-path": "src"
862+
}
863+
}
864+
```
865+
866+
To keep multiple version-specific configurations in the same file, use the
867+
`configs` array. Node.js will use the first entry whose `nodeVersion` matches
868+
the current Node.js major version:
869+
870+
```json
871+
{
872+
"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
873+
"configs": [
874+
{
875+
"nodeVersion": 25,
876+
"config": {
877+
"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
878+
"nodeOptions": {
879+
"watch-path": "src"
880+
}
881+
}
882+
}
883+
]
884+
}
885+
```
886+
887+
When `configs` is used, the top level may only contain `$schema` and
888+
`configs`. Each `configs` item must define an integer `nodeVersion` and an
889+
object `config`. A single top-level config does not require `nodeVersion`, but
890+
if present it must match the current Node.js major version.
891+
892+
When a namespace is present in the
893+
configuration file, Node.js automatically enables the corresponding flag
894+
(e.g., `--test`, `--watch`, `--permission`). This allows you to configure
895+
subsystem-specific options without explicitly passing the flag on the command line.
896+
897+
For example:
898+
899+
```json
900+
{
901+
"test": {
902+
"test-isolation": "process"
903+
}
904+
}
905+
```
906+
907+
is equivalent to:
908+
909+
```bash
910+
node --test --test-isolation=process
911+
```
912+
913+
To disable the automatic flag while still using namespace options, you can
914+
explicitly set the flag to `false` within the namespace:
915+
916+
```json
917+
{
918+
"test": {
919+
"test": false,
920+
"test-isolation": "process"
921+
}
922+
}
923+
```
924+
925+
No-op flags are not supported.
926+
Not all V8 flags are currently supported.
927+
928+
It is possible to use the [official JSON schema](../node-config-schema.json)
929+
to validate the configuration file, which may vary depending on the Node.js version.
930+
Each key in the configuration file corresponds to a flag that can be passed
931+
as a command-line argument. The value of the key is the value that would be
932+
passed to the flag.
933+
934+
For example, the configuration file above is equivalent to
935+
the following command-line arguments:
936+
937+
```bash
938+
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
939+
```
940+
941+
The priority in configuration is as follows:
942+
943+
1. NODE\_OPTIONS and command-line options
944+
2. Dotenv NODE\_OPTIONS
945+
3. Configuration file
946+
947+
Values in the configuration file will not override the values in the environment
948+
variables, command-line options, or the `NODE_OPTIONS` env file parsed by the
949+
`--env-file` flag.
950+
951+
Keys cannot be duplicated within the same or different namespaces.
952+
953+
The configuration parser will throw an error if the configuration file contains
954+
unknown keys or keys that cannot be used in a namespace.
955+
956+
Node.js will not sanitize or perform validation on the user-provided configuration,
957+
so **NEVER** use untrusted configuration files.
958+
802959
### `--cpu-prof`
803960

804961
<!-- YAML
@@ -1280,177 +1437,6 @@ added: v26.9.0
12801437
12811438
Enable the experimental `node:bench` module and command-line benchmark runner.
12821439

1283-
### `--experimental-config-file=path`, `--experimental-config-file`
1284-
1285-
<!-- YAML
1286-
added:
1287-
- v23.10.0
1288-
- v22.16.0
1289-
changes:
1290-
- version: v26.7.0
1291-
pr-url: https://github.com/nodejs/node/pull/64516
1292-
description: Marked as release candidate.
1293-
-->
1294-
1295-
> Stability: 1.2 - Release candidate
1296-
1297-
If present, Node.js will look for a configuration file at the specified path.
1298-
If the path is not specified, Node.js will look for a `node.config.json` file
1299-
in the current working directory.
1300-
To specify a custom path, use the `--experimental-config-file=path` form.
1301-
The space-separated `--experimental-config-file path` form is not supported.
1302-
The alias `--experimental-default-config-file` is equivalent to
1303-
`--experimental-config-file` without an argument.
1304-
Node.js will read the configuration file and apply the settings. The
1305-
configuration file should be a JSON file with the following structure. `vX.Y.Z`
1306-
in the `$schema` must be replaced with the version of Node.js you are using or
1307-
`latest-vX.x` for the latest version of that major release line.
1308-
1309-
```json
1310-
{
1311-
"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
1312-
"nodeOptions": {
1313-
"import": [
1314-
"amaro/strip"
1315-
],
1316-
"watch-path": "src",
1317-
"watch-preserve-output": true
1318-
},
1319-
"test": {
1320-
"test-isolation": "process"
1321-
},
1322-
"watch": {
1323-
"watch-preserve-output": true
1324-
}
1325-
}
1326-
```
1327-
1328-
The configuration file supports namespace-specific options:
1329-
1330-
* The `nodeOptions` field contains CLI flags that are allowed in [`NODE_OPTIONS`][].
1331-
1332-
* Namespace fields like `test`, `watch`, and `permission` contain configuration specific to that subsystem.
1333-
1334-
The configuration file can target a specific Node.js major version with
1335-
`nodeVersion`:
1336-
1337-
```json
1338-
{
1339-
"nodeVersion": 25,
1340-
"nodeOptions": {
1341-
"watch-path": "src"
1342-
}
1343-
}
1344-
```
1345-
1346-
To keep multiple version-specific configurations in the same file, use the
1347-
`configs` array. Node.js will use the first entry whose `nodeVersion` matches
1348-
the current Node.js major version:
1349-
1350-
```json
1351-
{
1352-
"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
1353-
"configs": [
1354-
{
1355-
"nodeVersion": 25,
1356-
"config": {
1357-
"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
1358-
"nodeOptions": {
1359-
"watch-path": "src"
1360-
}
1361-
}
1362-
}
1363-
]
1364-
}
1365-
```
1366-
1367-
When `configs` is used, the top level may only contain `$schema` and
1368-
`configs`. Each `configs` item must define an integer `nodeVersion` and an
1369-
object `config`. A single top-level config does not require `nodeVersion`, but
1370-
if present it must match the current Node.js major version.
1371-
1372-
When a namespace is present in the
1373-
configuration file, Node.js automatically enables the corresponding flag
1374-
(e.g., `--test`, `--watch`, `--permission`). This allows you to configure
1375-
subsystem-specific options without explicitly passing the flag on the command line.
1376-
1377-
For example:
1378-
1379-
```json
1380-
{
1381-
"test": {
1382-
"test-isolation": "process"
1383-
}
1384-
}
1385-
```
1386-
1387-
is equivalent to:
1388-
1389-
```bash
1390-
node --test --test-isolation=process
1391-
```
1392-
1393-
To disable the automatic flag while still using namespace options, you can
1394-
explicitly set the flag to `false` within the namespace:
1395-
1396-
```json
1397-
{
1398-
"test": {
1399-
"test": false,
1400-
"test-isolation": "process"
1401-
}
1402-
}
1403-
```
1404-
1405-
No-op flags are not supported.
1406-
Not all V8 flags are currently supported.
1407-
1408-
It is possible to use the [official JSON schema](../node-config-schema.json)
1409-
to validate the configuration file, which may vary depending on the Node.js version.
1410-
Each key in the configuration file corresponds to a flag that can be passed
1411-
as a command-line argument. The value of the key is the value that would be
1412-
passed to the flag.
1413-
1414-
For example, the configuration file above is equivalent to
1415-
the following command-line arguments:
1416-
1417-
```bash
1418-
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
1419-
```
1420-
1421-
The priority in configuration is as follows:
1422-
1423-
1. NODE\_OPTIONS and command-line options
1424-
2. Dotenv NODE\_OPTIONS
1425-
3. Configuration file
1426-
1427-
Values in the configuration file will not override the values in the environment
1428-
variables, command-line options, or the `NODE_OPTIONS` env file parsed by the
1429-
`--env-file` flag.
1430-
1431-
Keys cannot be duplicated within the same or different namespaces.
1432-
1433-
The configuration parser will throw an error if the configuration file contains
1434-
unknown keys or keys that cannot be used in a namespace.
1435-
1436-
Node.js will not sanitize or perform validation on the user-provided configuration,
1437-
so **NEVER** use untrusted configuration files.
1438-
1439-
### `--experimental-default-config-file`
1440-
1441-
<!-- YAML
1442-
added:
1443-
- v23.10.0
1444-
- v22.16.0
1445-
-->
1446-
1447-
> Stability: 1.0 - Early development
1448-
1449-
This flag is an alias for `--experimental-config-file` without an argument.
1450-
If present, Node.js will look for a
1451-
`node.config.json` file in the current working directory and load it as a
1452-
configuration file.
1453-
14541440
### `--experimental-dtls`
14551441

14561442
<!-- YAML

‎doc/api/permissions.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -375,9 +375,9 @@ programs.
375375
#### Configuration file support
376376

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

382382
Example `node.config.json`:
383383

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

402402
```console
403-
$ node --experimental-default-config-file app.js
403+
$ node --config-file app.js
404404
```
405405

406406
A configuration file, like the `NODE_OPTIONS` defined in an [`--env-file`][]
@@ -410,7 +410,7 @@ enable the Permission Model, the `allow-env` values these files define can only
410410
narrow the access that [`--allow-env`][] grants, and never widen it:
411411

412412
```console
413-
$ node --permission --allow-env=APP_* --experimental-config-file=node.config.json app.js
413+
$ node --permission --allow-env=APP_* --config-file=node.config.json app.js
414414
```
415415

416416
With `"allow-env": ["*"]` in `node.config.json`, only the variables starting with
@@ -539,6 +539,7 @@ Developers relying on --permission to sandbox untrusted code should be aware tha
539539
[`--allow-openssl-store`]: cli.md#--allow-openssl-store
540540
[`--allow-wasi`]: cli.md#--allow-wasi
541541
[`--allow-worker`]: cli.md#--allow-worker
542+
[`--config-file`]: cli.md#--config-filepath---config-file
542543
[`--env-file-if-exists`]: cli.md#--env-file-if-existsfile
543544
[`--env-file`]: cli.md#--env-filefile
544545
[`--permission-audit`]: cli.md#--permission-audit

0 commit comments

Comments
 (0)