Repository navigation
Expand file tree
/
Copy pathnodejs
More file actions
2651 lines (1607 loc) · 104 KB
/
Copy pathnodejs
File metadata and controls
2651 lines (1607 loc) · 104 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Node.js comes with a variety of CLI options. These options expose built-in debugging, multiple ways to execute scripts, and other helpful runtime options.
To view this documentation as a manual page in a terminal, run man node.
Synopsis
node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]
node inspect [<program-entry-point> | -e "script" | <host>:<port>] …
node --v8-options
Execute without arguments to start the REPL.
For more info about node inspect, see the debugger documentation.
Program entry point
The program entry point is a specifier-like string. If the string is not an absolute path, it's resolved as a relative path from the current working directory. That entry point string is then resolved as if it's been requested by require() from the current working directory. If no corresponding file is found, an error is thrown.
By default, the resolved path is also loaded as if it's been requested by require(), unless one of the conditions below apply—then it's loaded as if it's been requested by import():
The program was started with a command-line flag that forces the entry point to be loaded with ECMAScript module loader, such as --import.
The file has an .mjs, .mts or .wasm extension.
The file does not have a .cjs extension, and the nearest parent package.json file contains a top-level "type" field with a value of "module".
See module resolution and loading for more details.
Options
All options, including V8 options, allow words to be separated by both dashes (-) or underscores (_). For example, --pending-deprecation is equivalent to --pending_deprecation.
If an option that takes a single value (such as --max-http-header-size) is passed more than once, then the last passed value is used. Options from the command line take precedence over options passed through the NODE_OPTIONS environment variable.
-
Added in: v8.0.0
Alias for stdin. Analogous to the use of - in other command-line utilities, meaning that the script is read from stdin, and the rest of the options are passed to that script.
--
Added in: v6.11.0
Indicate the end of node options. Pass the rest of the arguments to the script. If no script filename or eval/print script is supplied prior to this, then the next argument is used as a script filename.
--abort-on-uncaught-exception
Added in: v0.10.8
Aborting instead of exiting causes a core file to be generated for post-mortem analysis using a debugger (such as lldb, gdb, and mdb).
If this flag is passed, the behavior can still be set to not abort through process.setUncaughtExceptionCaptureCallback() (and through usage of the node:domain module that uses it).
--allow-addons
Added in: v21.6.0, v20.12.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to use native addons by default. Attempts to do so will throw an ERR_DLOPEN_DISABLED unless the user explicitly passes the --allow-addons flag when starting Node.js.
Example:
// Attempt to require an native addon
require('nodejs-addon-example');
cjs
$ node --permission --allow-fs-read=* index.js
node:internal/modules/cjs/loader:1319
return process.dlopen(module, path.toNamespacedPath(filename));
^
Error: Cannot load native addon because loading addons is disabled.
at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)
at Module.load (node:internal/modules/cjs/loader:1091:32)
at Module._load (node:internal/modules/cjs/loader:938:12)
at Module.require (node:internal/modules/cjs/loader:1115:19)
at require (node:internal/modules/helpers:130:18)
at Object.<anonymous> (/home/index.js:1:15)
at Module._compile (node:internal/modules/cjs/loader:1233:14)
at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
at Module.load (node:internal/modules/cjs/loader:1091:32)
at Module._load (node:internal/modules/cjs/loader:938:12) {
code: 'ERR_DLOPEN_DISABLED'
}
console
--allow-child-process
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to spawn any child process by default. Attempts to do so will throw an ERR_ACCESS_DENIED unless the user explicitly passes the --allow-child-process flag when starting Node.js.
Example:
const childProcess = require('node:child_process');
// Attempt to bypass the permission
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);
js
$ node --permission --allow-fs-read=* index.js
node:internal/child_process:388
const err = this._handle.spawn(options);
^
Error: Access to this API has been restricted
at ChildProcess.spawn (node:internal/child_process:388:28)
at node:internal/main/run_main_module:17:47 {
code: 'ERR_ACCESS_DENIED',
permission: 'ChildProcess'
}
console
The child_process.fork() API inherits the execution arguments from the parent process. This means that if Node.js is started with the Permission Model enabled and the --allow-child-process flag is set, any child process created using child_process.fork() will automatically receive all relevant Permission Model flags.
This behavior also applies to child_process.spawn(), but in that case, the flags are propagated via the NODE_OPTIONS environment variable rather than directly through the process arguments.
--allow-ffi
Added in: v26.1.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to use FFI APIs by default. Attempts to use FFI APIs will throw an ERR_ACCESS_DENIED exception unless the user explicitly passes the --allow-ffi flag when starting Node.js. The node:ffi module is only available in builds with FFI support.
Example:
const { DynamicLibrary, suffix } = require('node:ffi');
const lib = new DynamicLibrary(`./mylib.${suffix}`);
js
$ node --permission index.js
Error: Access to this API has been restricted. Use --allow-ffi to manage permissions.
at node:internal/main/run_main_module:17:47 {
code: 'ERR_ACCESS_DENIED',
permission: 'FFI'
}
console
--allow-fs-read
This flag configures file system read permissions using the Permission Model.
The valid arguments for the --allow-fs-read flag are:
* - To allow all FileSystemRead operations.
Multiple paths can be allowed using multiple --allow-fs-read flags. Example --allow-fs-read=/folder1/ --allow-fs-read=/folder2/
Examples can be found in the File System Permissions documentation.
The initializer module and custom --require modules has a implicit read permission.
$ node --permission -r custom-require.js -r custom-require-2.js index.js
console
The custom-require.js, custom-require-2.js, and index.js will be by default in the allowed read list.
process.permission.has('fs.read', 'index.js'); // true
process.permission.has('fs.read', 'custom-require.js'); // true
process.permission.has('fs.read', 'custom-require-2.js'); // true
js
--allow-fs-vfs
Added in: v26.9.0
Stability: 1.1 - Active development
When using the Permission Model, a virtual file system cannot be mounted by default: vfs.mount() throws ERR_INVALID_STATE unless the user explicitly passes the --allow-fs-vfs flag when starting Node.js.
A mounted VFS serves paths that the file system permissions do not describe, so mounting one is gated on its own flag rather than on --allow-fs-read or --allow-fs-write.
$ node --experimental-vfs --permission --allow-fs-vfs app.js
console
--allow-fs-write
This flag configures file system write permissions using the Permission Model.
The valid arguments for the --allow-fs-write flag are:
* - To allow all FileSystemWrite operations.
Multiple paths can be allowed using multiple --allow-fs-write flags. Example --allow-fs-write=/folder1/ --allow-fs-write=/folder2/
Paths delimited by comma (,) are no longer allowed. When passing a single flag with a comma a warning will be displayed.
Examples can be found in the File System Permissions documentation.
--allow-inspector
Added in: v25.0.0, v24.12.0
Stability: 1.0 - Early development
When using the Permission Model, the process will not be able to connect through inspector protocol.
Attempts to do so will throw an ERR_ACCESS_DENIED unless the user explicitly passes the --allow-inspector flag when starting Node.js.
Example:
const { Session } = require('node:inspector/promises');
const session = new Session();
session.connect();
js
$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.
code: 'ERR_ACCESS_DENIED',
}
console
--allow-net
Added in: v25.0.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to access network by default. Attempts to do so will throw an ERR_ACCESS_DENIED unless the user explicitly passes the --allow-net flag when starting Node.js.
Example:
const http = require('node:http');
// Attempt to bypass the permission
const req = http.get('http://example.com', () => {});
req.on('error', (err) => {
console.log('err', err);
});
js
$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.
code: 'ERR_ACCESS_DENIED',
}
console
--allow-openssl-store
Added in: v26.7.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to use OpenSSL STORE loaders by default, for example to load a private key from a <URL> passed to crypto.createPrivateKey(). Attempts to do so will throw an ERR_ACCESS_DENIED unless the user explicitly passes the --allow-openssl-store flag. This permission can be dropped at runtime via permission.drop().
This flag grants broad authority to configured OpenSSL STORE loaders. A loader may access files, devices, tokens, or the network. Access performed by a loader is not constrained by the fs.read, fs.write, or net permission scopes.
--allow-wasi
Added in: v22.3.0, v20.16.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be capable of creating any WASI instances by default. For security reasons, the call will throw an ERR_ACCESS_DENIED unless the user explicitly passes the flag --allow-wasi in the main Node.js process.
Example:
const { WASI } = require('node:wasi');
// Attempt to bypass the permission
new WASI({
version: 'preview1',
// Attempt to mount the whole filesystem
preopens: {
'/': '/',
},
});
js
$ node --permission --allow-fs-read=* index.js
Error: Access to this API has been restricted
at node:internal/main/run_main_module:30:49 {
code: 'ERR_ACCESS_DENIED',
permission: 'WASI',
}
console
--allow-worker
Added in: v20.0.0
Stability: 1.1 - Active development
When using the Permission Model, the process will not be able to create any worker threads by default. For security reasons, the call will throw an ERR_ACCESS_DENIED unless the user explicitly pass the flag --allow-worker in the main Node.js process.
Example:
const { Worker } = require('node:worker_threads');
// Attempt to bypass the permission
new Worker(__filename);
js
$ node --permission --allow-fs-read=* index.js
Error: Access to this API has been restricted
at node:internal/main/run_main_module:17:47 {
code: 'ERR_ACCESS_DENIED',
permission: 'WorkerThreads'
}
console
--bench
Added in: v26.9.0
Stability: 1 - Experimental
Starts the Node.js command-line benchmark runner. At least one explicit file or glob pattern is required:
node --experimental-bench --bench benchmark.mjs
node --experimental-bench --bench 'benchmarks/**/*.js'
console
The --experimental-bench flag is required to use this flag or any other --bench-* option.
Quote glob patterns to prevent expansion by the shell. Matching files are sorted and executed serially. By default, each file runs in a separate child process. Benchmark files declare benchmarks using node:bench; they must not call run() themselves. See the benchmark runner documentation for more details.
This flag cannot be combined with --test, --watch, --watch-path, --check, --eval, or --interactive.
--bench-isolation=mode
Added in: v26.9.0
Stability: 1 - Experimental
Configures benchmark file isolation. When mode is 'process', each matching file runs in a separate child process. This is the default. Files are still run serially so their measured work does not overlap.
When mode is 'none', all matching files and benchmarks run serially in the benchmark runner process. This reduces startup overhead but allows module, heap, and process state to carry between files. User writes to stdout or stderr also share destinations with benchmark reporters in this mode.
The supported modes are 'process' and 'none'.
--bench-name-pattern=pattern
Added in: v26.9.0
Stability: 1 - Experimental
Only runs benchmarks whose full hierarchical name matches the JavaScript regular expression pattern. Non-matching benchmarks are reported as skipped.
--bench-reporter-destination=destination
Added in: v26.9.0
Stability: 1 - Experimental
Specifies the destination for the corresponding benchmark reporter. The value can be stdout, stderr, or a file path. A single reporter defaults to stdout when no destination is specified.
--bench-reporter=reporter
Added in: v26.9.0
Stability: 1 - Experimental
Specifies a benchmark reporter. The built-in reporters are spec and json. The json reporter emits newline-delimited JSON. A custom reporter can be specified using a module specifier resolved from the current working directory.
This option can be repeated. When multiple reporters are specified, each must have a corresponding --bench-reporter-destination. The default reporter is spec.
--bench-samples=count
Added in: v26.9.0
Stability: 1 - Experimental
Overrides the maximum number of measured callback invocations for every selected benchmark. A benchmark may finish earlier by calling context.done(). count must be an integer between 1 and 4294967295.
--bench-warmup=count
Added in: v26.9.0
Stability: 1 - Experimental
Overrides the number of unreported warmup callback invocations for every selected benchmark. count must be an integer between 0 and 4294967295. Without this option, each benchmark uses its own warmup value, which defaults to 10.
--build-sea=config
Added in: v25.5.0
Stability: 1.1 - Active development
Generates a single executable application from a JSON configuration file. The argument must be a path to the configuration file. If the path is not absolute, it is resolved relative to the current working directory.
For configuration fields, cross-platform notes, and asset APIs, see the single executable application documentation.
--build-snapshot
Generates a snapshot blob when the process exits and writes it to disk, which can be loaded later with --snapshot-blob.
When building the snapshot, if --snapshot-blob is not specified, the generated blob will be written, by default, to snapshot.blob in the current working directory. Otherwise it will be written to the path specified by --snapshot-blob.
$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js
# Run snapshot.js to initialize the application and snapshot the
# state of it into snapshot.blob.
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js
$ echo "console.log(globalThis.foo)" > index.js
# Load the generated snapshot and start the application from index.js.
$ node --snapshot-blob snapshot.blob index.js
I am from the snapshot
console
The v8.startupSnapshot API can be used to specify an entry point at snapshot building time, thus avoiding the need of an additional entry script at deserialization time:
$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js
$ node --snapshot-blob snapshot.blob
I am from the snapshot
console
For more information, check out the v8.startupSnapshot API documentation.
The snapshot currently only supports loading a single entrypoint during the snapshot building process, which can load built-in modules, but not additional user-land modules. Users can bundle their applications into a single script with their bundler of choice before building a snapshot.
As it's complicated to ensure the serializablility of all built-in modules, which are also growing over time, only a subset of the built-in modules are well tested to be serializable during the snapshot building process. The Node.js core test suite checks that a few fairly complex applications can be snapshotted. The list of built-in modules being captured by the built-in snapshot of Node.js is considered supported. When the snapshot builder encounters a built-in module that cannot be serialized, it may crash the snapshot building process. In that case a typical workaround would be to delay loading that module until runtime, using either v8.startupSnapshot.setDeserializeMainFunction() or v8.startupSnapshot.addDeserializeCallback(). If serialization for an additional module during the snapshot building process is needed, please file a request in the Node.js issue tracker and link to it in the tracking issue for user-land snapshots.
--build-snapshot-config
Specifies the path to a JSON configuration file which configures snapshot creation behavior.
The following options are currently supported:
builder <string> Required. Provides the name to the script that is executed before building the snapshot, as if --build-snapshot had been passed with builder as the main script name.
withoutCodeCache <boolean> Optional. Including the code cache reduces the time spent on compiling functions included in the snapshot at the expense of a bigger snapshot size and potentially breaking portability of the snapshot.
When using this flag, additional script files provided on the command line will not be executed and instead be interpreted as regular command line arguments.
-c, --check
Syntax check the script without executing.
--completion-bash
Added in: v10.12.0
Print source-able bash completion script for Node.js.
node --completion-bash > node_bash_completion
source node_bash_completion
bash
-C condition, --conditions=condition
Provide custom conditional exports resolution conditions.
Any number of custom string condition names are permitted.
The default Node.js conditions of "node", "default", "import", and "require" will always apply as defined.
For example, to run a module with "development" resolutions:
node -C development app.js
bash
--config-file=path, --config-file
If present, Node.js will look for a configuration file at the specified path. If the path is not specified, Node.js will look for a node.config.json file in the current working directory. To specify a custom path, use the --config-file=path form. The space-separated --config-file path form is not supported. Node.js will read the configuration file and apply the settings. The configuration file should be a JSON file with the following structure. vX.Y.Z in the $schema must be replaced with the version of Node.js you are using or latest-vX.x for the latest version of that major release line.
{
"$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
"nodeOptions": {
"import": [
"amaro/strip"
],
"watch-path": "src",
"watch-preserve-output": true
},
"test": {
"test-isolation": "process"
},
"watch": {
"watch-preserve-output": true
}
}
json
The configuration file supports namespace-specific options:
The nodeOptions field contains CLI flags that are allowed in NODE_OPTIONS.
Namespace fields like test, watch, and permission contain configuration specific to that subsystem.
The configuration file can target a specific Node.js major version with nodeVersion:
{
"nodeVersion": 25,
"nodeOptions": {
"watch-path": "src"
}
}
json
To keep multiple version-specific configurations in the same file, use the configs array. Node.js will use the first entry whose nodeVersion matches the current Node.js major version:
{
"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
"configs": [
{
"nodeVersion": 25,
"config": {
"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
"nodeOptions": {
"watch-path": "src"
}
}
}
]
}
json
When configs is used, the top level may only contain $schema and configs. Each configs item must define an integer nodeVersion and an object config. A single top-level config does not require nodeVersion, but if present it must match the current Node.js major version.
When a namespace is present in the configuration file, Node.js automatically enables the corresponding flag (e.g., --test, --watch, --permission). This allows you to configure subsystem-specific options without explicitly passing the flag on the command line.
For example:
{
"test": {
"test-isolation": "process"
}
}
json
is equivalent to:
node --test --test-isolation=process
bash
To disable the automatic flag while still using namespace options, you can explicitly set the flag to false within the namespace:
{
"test": {
"test": false,
"test-isolation": "process"
}
}
json
No-op flags are not supported. Not all V8 flags are currently supported.
It is possible to use the official JSON schema 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 passed to the flag.
For example, the configuration file above is equivalent to the following command-line arguments:
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
bash
The priority in configuration is as follows:
NODE_OPTIONS and command-line options
Dotenv NODE_OPTIONS
Configuration file
Values in the configuration file will not override the values in the environment 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.
The configuration parser will throw an error if the configuration file contains unknown keys or keys that cannot be used in a namespace.
Node.js will not sanitize or perform validation on the user-provided configuration, so NEVER use untrusted configuration files.
--cpu-prof
Starts the V8 CPU profiler on start up, and writes the CPU profile to disk before exit.
If --cpu-prof-dir is not specified, the generated profile is placed in the current working directory.
If --cpu-prof-name is not specified, the generated profile is named CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile.
$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile
console
If --cpu-prof-name is specified, the provided value is used as a template for the file name. The following placeholder is supported and will be substituted at runtime:
${pid} — the current process ID
$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
$ ls *.cpuprofile
CPU.15293.cpuprofile
console
--cpu-prof-dir
Specify the directory where the CPU profiles generated by --cpu-prof will be placed.
The default value is controlled by the --diagnostic-dir command-line option.
--cpu-prof-interval
Specify the sampling interval in microseconds for the CPU profiles generated by --cpu-prof. The default is 1000 microseconds.
--cpu-prof-name
Specify the file name of the CPU profile generated by --cpu-prof.
--diagnostic-dir=directory
Set the directory to which all diagnostic output files are written. Defaults to current working directory.
Affects the default output directory of:
--cpu-prof-dir
--heap-prof-dir
--redirect-warnings
--disable-proto=mode
Added in: v13.12.0, v12.17.0
Disable the Object.prototype.__proto__ property. If mode is delete, the property is removed entirely. If mode is throw, accesses to the property throw an exception with the code ERR_PROTO_ACCESS.
--disable-sigusr1
Disable the ability of starting a debugging session by sending a SIGUSR1 signal to the process.
--disable-warning=code-or-type
Disable specific process warnings by code or type.
Warnings emitted from process.emitWarning() may contain a code and a type. This option will not-emit warnings that have a matching code or type.
List of deprecation warnings.
The Node.js core warning types are: DeprecationWarning and ExperimentalWarning
For example, the following script will not emit DEP0025 require('node:sys') when executed with node --disable-warning=DEP0025:
const sys = require('node:sys');
javascript
For example, the following script will emit the DEP0025 require('node:sys'), but not any Experimental Warnings (such as ExperimentalWarning: vm.measureMemory is an experimental feature in <=v21) when executed with node --disable-warning=ExperimentalWarning:
const sys = require('node:sys');
const vm = require('node:vm');
vm.measureMemory();
javascript
--disable-wasm-trap-handler
Node.js enables V8's trap-handler-based WebAssembly bound checks on 64-bit platforms, which significantly improves WebAssembly performance by eliminating the need for inline bound checks. This optimization requires allocating a large virtual memory cage per WebAssembly memory instance (currently typically 8GB for 32-bit WebAssembly memory, 16GB for 64-bit WebAssembly memory) to trap out-of-bound accesses. On most 64-bit platforms, the virtual memory address space is usually large enough (around 128TB) to accommodate typical WebAssembly usages, but if the machine has manual limits on virtual memory (e.g. through ulimit -v), WebAssembly memory allocation is more likely to fail with WebAssembly.Memory(): could not allocate memory.
At startup, Node.js automatically checks whether there is enough virtual memory available to allocate at least one cage, and if not, the trap-handler optimization is automatically disabled so that WebAssembly can still run using inline bound checks (with less optimal performance). But if the application needs to create many WebAssembly memory instances and the machine still configures a relatively high limit on virtual memory, allocation of WebAssembly memory instances may still fail more quickly than expected due to the raised virtual memory usage.
--disable-wasm-trap-handler fully disables this optimization so that WebAssembly memory instances always use inline bound checks instead of reserving large virtual memory cages. This allows more instances to be created when the virtual memory address space available to the Node.js process is limited.
--disallow-code-generation-from-strings
Added in: v9.8.0
Make built-in language features like eval and new Function that generate code from strings throw an exception instead. This does not affect the Node.js node:vm module.
--dns-result-order=order
Set the default value of order in dns.lookup() and dnsPromises.lookup(). The value could be:
ipv4first: sets default order to ipv4first.
ipv6first: sets default order to ipv6first.
verbatim: sets default order to verbatim.
The default is verbatim and dns.setDefaultResultOrder() have higher priority than --dns-result-order.
--enable-fips
Added in: v6.0.0
Enable FIPS mode at startup. With OpenSSL 3, a configured provider named fips must be available and initialize successfully. With OpenSSL 1.1.1, Node.js must be built against a FIPS-capable OpenSSL.
--enable-fips-indicator-events
Added in: v26.9.0
Publish OpenSSL FIPS indicator results to the 'crypto.fips.indicator' diagnostics channel. This option requires OpenSSL 3.4 or later. It does not enable FIPS mode or change whether an operation is permitted.
--enable-source-maps
Enable Source Map support for stack traces.
When using a transpiler, such as TypeScript, stack traces thrown by an application reference the transpiled code, not the original source position. --enable-source-maps enables caching of Source Maps and makes a best effort to report stack traces relative to the original source file.
Overriding Error.prepareStackTrace may prevent --enable-source-maps from modifying the stack trace. Call and return the results of the original Error.prepareStackTrace in the overriding function to modify the stack trace with source maps.
const originalPrepareStackTrace = Error.prepareStackTrace;
Error.prepareStackTrace = (error, trace) => {
// Modify error and trace and format stack trace with
// original Error.prepareStackTrace.
return originalPrepareStackTrace(error, trace);
};
js
Note, enabling source maps can introduce latency to your application when Error.stack is accessed. If you access Error.stack frequently in your application, take into account the performance implications of --enable-source-maps.
--entry-url
Added in: v23.0.0, v22.10.0
Stability: 1 - Experimental
When present, Node.js will interpret the entry point as a URL, rather than a path.
Follows ECMAScript module resolution rules.
Any query parameter or hash in the URL will be accessible via import.meta.url.
node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'
node --entry-url 'file.ts?query#hash'
node --entry-url 'data:text/javascript,console.log("Hello")'
bash
--env-file-if-exists=file
Behavior is the same as --env-file, but an error is not thrown if the file does not exist.
--env-file=file
Loads environment variables from a file relative to the current directory, making them available to applications on process.env. The environment variables which configure Node.js, such as NODE_OPTIONS, are parsed and applied. If the same variable is defined in the environment and in the file, the value from the environment takes precedence.
You can pass multiple --env-file arguments. Subsequent files override pre-existing variables defined in previous files.
An error is thrown if the file does not exist.
node --env-file=.env --env-file=.development.env index.js
bash
The format of the file should be one line per key-value pair of environment variable name and value separated by =:
PORT=3000
text
Any text after a # is treated as a comment:
# This is a comment
PORT=3000 # This is also a comment
text
Values can start and end with the following quotes: `, " or '. They are omitted from the values.
USERNAME="nodejs" # will result in `nodejs` as the value.
text
Multi-line values are supported:
MULTI_LINE="THIS IS
A MULTILINE"
# will result in `THIS IS\nA MULTILINE` as the value.
text
Export keyword before a key is ignored:
export USERNAME="nodejs" # will result in `nodejs` as the value.
text
If you want to load environment variables from a file that may not exist, you can use the --env-file-if-exists flag instead.
-e, --eval "script"
Evaluate the following argument as JavaScript. The modules which are predefined in the REPL can also be used in script.
If script starts with -, pass it using = (for example, node --print --eval=-42) so it is parsed as the value of --eval.
On Windows, using cmd.exe a single quote will not work correctly because it only recognizes double " for quoting. In Powershell or Git bash, both ' and " are usable.
It is possible to run code containing inline types unless the --no-strip-types flag is provided.
--experimental-addon-modules
Stability: 1.2 - Release candidate
Enable experimental import support for .node addons.
--experimental-bench
Added in: v26.9.0
Stability: 1 - Experimental
Enable the experimental node:bench module and command-line benchmark runner.
--experimental-dtls
Added in: v26.9.0
Stability: 1 - Experimental
Enable experimental support for the DTLS protocol. See the dtls documentation for details.
--experimental-eventsource
Added in: v22.3.0, v20.18.0
Enable exposition of EventSource Web API on the global scope.
--experimental-import-meta-resolve
Enable experimental import.meta.resolve() parent URL support, which allows passing a second parentURL argument for contextual resolution.
Previously gated the entire import.meta.resolve feature.
--experimental-import-text
Added in: v26.5.0
Stability: 1.0 - Early development
Enable experimental support for importing modules with with { type: 'text' }.
--experimental-inspector-network-resource
Added in: v24.5.0, v22.19.0
Stability: 1.1 - Active Development
Enable experimental support for inspector network resources.
--experimental-loader=module
This flag is discouraged and may be removed in a future version of Node.js. Please use --import with register() instead.
Specify the module containing exported asynchronous module customization hooks. module may be any string accepted as an import specifier.
This feature requires --allow-worker if used with the Permission Model.
--experimental-network-inspection
Added in: v22.6.0, v20.18.0
Stability: 1 - Experimental
Enable experimental support for the network inspection with Chrome DevTools.
--experimental-package-map=<path>
Added in: v26.4.0
Stability: 1 - Experimental
Enable experimental package map resolution. The path argument specifies the location of a JSON configuration file that defines package resolution mappings.
node --experimental-package-map=./package-map.json app.js
bash
When enabled, bare specifier resolution consults the package map for resolution. This allows explicit control over which packages can import which dependencies.
See Package maps for details on the configuration file format and resolution algorithm.
--experimental-print-required-tla
If the ES module graph cannot be require()'d because it contains any top-level await, this flag allows Node.js to locate and print their locations.
--experimental-quic
Added in: v25.0.0
Stability: 1.1 - Active development
Enable experimental support for the QUIC protocol.
--experimental-sea-config
Added in: v20.0.0
Stability: 1 - Experimental
Use this flag to generate a blob that can be injected into the Node.js binary to produce a single executable application. See the documentation about this configuration for details.
--experimental-shadow-realm
Added in: v19.0.0, v18.13.0
Use this flag to enable ShadowRealm support.
--experimental-storage-inspection
Added in: v25.5.0
Stability: 1.1 - Active Development
Enable experimental support for storage inspection
--experimental-stream-iter
Added in: v25.9.0
Stability: 1 - Experimental
Enable the experimental node:stream/iter module.
--experimental-test-coverage
When used in conjunction with the node:test module, a code coverage report is generated as part of the test runner output. If no tests are run, a coverage report is not generated. See the documentation on collecting code coverage from tests for more details.
--experimental-test-module-mocks
Stability: 1.0 - Early development
Enable module mocking in the test runner.
This feature requires --allow-worker if used with the Permission Model.
--experimental-test-tag-filter='<expr>'
Added in: v26.2.0
Stability: 1.0 - Early development
Run only tests that match the provided boolean tag-filter expression. Tests declare tags via the tags option on test(), it(), suite(), or describe(). Tags inherit from suites to nested tests by union.
The expression supports boolean operators (and/&&, or/||, not/!), parentheses for grouping, and * wildcards inside identifiers. Standard precedence applies: not binds tighter than and, which binds tighter than or. See Test tags for the full grammar and behavior.
The flag may be specified more than once; multiple expressions are combined with AND, so a test must satisfy every expression to run.
A malformed expression causes the test runner to exit with a non-zero status before running any tests.
--experimental-vfs
Added in: v26.4.0
Stability: 1 - Experimental
Enable the experimental node:vfs module.
--experimental-vm-modules
Added in: v9.6.0
Enable experimental ES Module support in the node:vm module.
--experimental-wasi-unstable-preview1
Enable experimental WebAssembly System Interface (WASI) support.
--experimental-web-worker
Added in: v26.9.0
Enable experimental support for the Web Worker API.
--experimental-worker-inspection
Added in: v24.1.0, v22.17.0
Stability: 1.1 - Active Development
Enable experimental support for the worker inspection with Chrome DevTools.
--force-context-aware
Added in: v12.12.0
Disable loading native addons that are not context-aware.
--force-fips[=mode]
Enable FIPS mode at startup and prevent it from being disabled from script code. The same OpenSSL requirements as --enable-fips apply.
An optional mode can be specified using --force-fips=mode:
provider: Preserve the OpenSSL FIPS provider's configured handling of non-approved operations. This is the current default when the mode is omitted.
strict: Reject non-approved operations reported through the OpenSSL FIPS indicator callback. This mode requires OpenSSL 3.4 or later.
The strict mode only covers operations reported through the callback for OpenSSL's default library context. It does not cover native addons that use another OSSL_LIB_CTX or another copy of libcrypto, nor operation-specific indicators that do not invoke the callback.
--force-node-api-uncaught-exceptions-policy
Added in: v18.3.0, v16.17.0
Enforces uncaughtException event on Node-API asynchronous callbacks.
To prevent from an existing add-on from crashing the process, this flag is not enabled by default. In the future, this flag will be enabled by default to enforce the correct behavior.
--frozen-intrinsics
Added in: v11.12.0
Stability: 1 - Experimental
Enable experimental frozen intrinsics like Array and Object.
Only the root context is supported. There is no guarantee that globalThis.Array is indeed the default intrinsic reference. Code may break under this flag.
To allow polyfills to be added, --require and --import both run before freezing intrinsics.
--heap-prof
Starts the V8 heap profiler on start up, and writes the heap profile to disk before exit.
If --heap-prof-dir is not specified, the generated profile is placed in the current working directory.
If --heap-prof-name is not specified, the generated profile is named Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile.
$ node --heap-prof index.js
$ ls *.heapprofile
Heap.20190409.202950.15293.0.001.heapprofile
console
--heap-prof-dir
Specify the directory where the heap profiles generated by --heap-prof will be placed.
The default value is controlled by the --diagnostic-dir command-line option.
--heap-prof-interval
Specify the average sampling interval in bytes for the heap profiles generated by --heap-prof. The default is 512 * 1024 bytes.
--heap-prof-name
Specify the file name of the heap profile generated by --heap-prof.