5ff1eab951PR-URL: https://github.com/nodejs/node/pull/61747 Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com> Reviewed-By: Ethan Arrowood <ethan@arrowood.dev> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
2346 lines
85 KiB
Groff
2346 lines
85 KiB
Groff
.\"
|
||
.\" This manpage is written in mdoc(7).
|
||
.\"
|
||
.\" * Language reference:
|
||
.\" https://man.openbsd.org/mdoc.7
|
||
.\"
|
||
.\" * Linting changes:
|
||
.\" mandoc -Wall -Tlint /path/to/this.file # BSD
|
||
.\" groff -w all -z /path/to/this.file # GNU/Linux, macOS
|
||
.\"
|
||
.\"
|
||
.\" Before making changes, please note the following:
|
||
.\"
|
||
.\" * In Roff, each new sentence should begin on a new line. This gives
|
||
.\" the Roff formatter better control over text-spacing, line-wrapping,
|
||
.\" and paragraph justification.
|
||
.\"
|
||
.\" * Do not leave blank lines in the markup. If whitespace is desired
|
||
.\" for readability, put a dot in the first column to indicate a null/empty
|
||
.\" command. Comments and horizontal whitespace may optionally follow: each
|
||
.\" of these lines are an example of a null command immediately followed by
|
||
.\" a comment.
|
||
.\"
|
||
.\"======================================================================
|
||
.
|
||
.Dd $Mdocdate$
|
||
.Dt NODE 1
|
||
.
|
||
.Sh NAME
|
||
.Nm node
|
||
.Nd server-side JavaScript runtime
|
||
.
|
||
.Sh SYNOPSIS
|
||
.Nm node
|
||
.Op Ar options
|
||
.Op Ar v8 options
|
||
.Op Ar <program-entry-point> | Fl e Ar string | Fl -
|
||
.Op Ar arguments ...
|
||
.
|
||
.Nm node
|
||
.Cm inspect,
|
||
.Op Ar <program-entry-point> | Fl e Ar string | Ar <host>:<port>
|
||
.Ar ...
|
||
.
|
||
.Nm node
|
||
.Op Fl -v8-options
|
||
.
|
||
.Sh DESCRIPTION
|
||
Node.js is a set of libraries for JavaScript which allows it to be used outside of the browser.
|
||
It is primarily focused on creating simple, easy-to-build network clients and servers.
|
||
.Pp
|
||
Execute
|
||
.Nm
|
||
without arguments to start a REPL.
|
||
.
|
||
.Sh OPTIONS
|
||
.Bl -tag -width 6n
|
||
.It Fl
|
||
Alias for stdin. Analogous to the use of \fB-\fR in other command-line utilities,
|
||
meaning that the script is read from stdin, and the rest of the options
|
||
are passed to that script.
|
||
.
|
||
.It Fl -
|
||
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.
|
||
.
|
||
.It Fl -abort-on-uncaught-exception
|
||
Aborting instead of exiting causes a core file to be generated for post-mortem
|
||
analysis using a debugger (such as \fBlldb\fR, \fBgdb\fR, and \fBmdb\fR).
|
||
If this flag is passed, the behavior can still be set to not abort through
|
||
\fBprocess.setUncaughtExceptionCaptureCallback()\fR (and through usage of the
|
||
\fBnode:domain\fR module that uses it).
|
||
.
|
||
.It Fl -allow-addons
|
||
When using the Permission Model, the process will not be able to use
|
||
native addons by default.
|
||
Attempts to do so will throw an \fBERR_DLOPEN_DISABLED\fR unless the
|
||
user explicitly passes the \fB--allow-addons\fR flag when starting Node.js.
|
||
Example:
|
||
.Bd -literal
|
||
// Attempt to require an native addon
|
||
require('nodejs-addon-example');
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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'
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -allow-child-process
|
||
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 \fBERR_ACCESS_DENIED\fR unless the
|
||
user explicitly passes the \fB--allow-child-process\fR flag when starting Node.js.
|
||
Example:
|
||
.Bd -literal
|
||
const childProcess = require('node:child_process');
|
||
// Attempt to bypass the permission
|
||
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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'
|
||
}
|
||
.Ed
|
||
The \fBchild_process.fork()\fR API inherits the execution arguments from the
|
||
parent process. This means that if Node.js is started with the Permission
|
||
Model enabled and the \fB--allow-child-process\fR flag is set, any child process
|
||
created using \fBchild_process.fork()\fR will automatically receive all relevant
|
||
Permission Model flags.
|
||
This behavior also applies to \fBchild_process.spawn()\fR, but in that case, the
|
||
flags are propagated via the \fBNODE_OPTIONS\fR environment variable rather than
|
||
directly through the process arguments.
|
||
.
|
||
.It Fl -allow-fs-read
|
||
This flag configures file system read permissions using
|
||
the Permission Model.
|
||
The valid arguments for the \fB--allow-fs-read\fR flag are:
|
||
.Bl -bullet
|
||
.It
|
||
\fB*\fR - To allow all \fBFileSystemRead\fR operations.
|
||
.It
|
||
Multiple paths can be allowed using multiple \fB--allow-fs-read\fR flags.
|
||
Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder1/\fR
|
||
.El
|
||
Examples can be found in the File System Permissions documentation.
|
||
The initializer module and custom \fB--require\fR modules has a implicit
|
||
read permission.
|
||
.Bd -literal
|
||
$ node --permission -r custom-require.js -r custom-require-2.js index.js
|
||
.Ed
|
||
.Bl -bullet
|
||
.It
|
||
The \fBcustom-require.js\fR, \fBcustom-require-2.js\fR, and \fBindex.js\fR will be
|
||
by default in the allowed read list.
|
||
.El
|
||
.Bd -literal
|
||
process.has('fs.read', 'index.js'); // true
|
||
process.has('fs.read', 'custom-require.js'); // true
|
||
process.has('fs.read', 'custom-require-2.js'); // true
|
||
.Ed
|
||
.
|
||
.It Fl -allow-fs-write
|
||
This flag configures file system write permissions using
|
||
the Permission Model.
|
||
The valid arguments for the \fB--allow-fs-write\fR flag are:
|
||
.Bl -bullet
|
||
.It
|
||
\fB*\fR - To allow all \fBFileSystemWrite\fR operations.
|
||
.It
|
||
Multiple paths can be allowed using multiple \fB--allow-fs-write\fR flags.
|
||
Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder1/\fR
|
||
.El
|
||
Paths delimited by comma (\fB,\fR) 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.
|
||
.
|
||
.It Fl -allow-inspector
|
||
When using the Permission Model, the process will not be able to connect
|
||
through inspector protocol.
|
||
Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the
|
||
user explicitly passes the \fB--allow-inspector\fR flag when starting Node.js.
|
||
Example:
|
||
.Bd -literal
|
||
const { Session } = require('node:inspector/promises');
|
||
|
||
const session = new Session();
|
||
session.connect();
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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',
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -allow-net
|
||
When using the Permission Model, the process will not be able to access
|
||
network by default.
|
||
Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the
|
||
user explicitly passes the \fB--allow-net\fR flag when starting Node.js.
|
||
Example:
|
||
.Bd -literal
|
||
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);
|
||
});
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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',
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -allow-wasi
|
||
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 \fBERR_ACCESS_DENIED\fR unless the
|
||
user explicitly passes the flag \fB--allow-wasi\fR in the main Node.js process.
|
||
Example:
|
||
.Bd -literal
|
||
const { WASI } = require('node:wasi');
|
||
// Attempt to bypass the permission
|
||
new WASI({
|
||
version: 'preview1',
|
||
// Attempt to mount the whole filesystem
|
||
preopens: {
|
||
'/': '/',
|
||
},
|
||
});
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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',
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -allow-worker
|
||
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 \fBERR_ACCESS_DENIED\fR unless the
|
||
user explicitly pass the flag \fB--allow-worker\fR in the main Node.js process.
|
||
Example:
|
||
.Bd -literal
|
||
const { Worker } = require('node:worker_threads');
|
||
// Attempt to bypass the permission
|
||
new Worker(__filename);
|
||
.Ed
|
||
.Bd -literal
|
||
$ 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'
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -build-sea Ns = Ns Ar config
|
||
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.
|
||
.
|
||
.It Fl -build-snapshot
|
||
Generates a snapshot blob when the process exits and writes it to
|
||
disk, which can be loaded later with \fB--snapshot-blob\fR.
|
||
When building the snapshot, if \fB--snapshot-blob\fR is not specified,
|
||
the generated blob will be written, by default, to \fBsnapshot.blob\fR
|
||
in the current working directory. Otherwise it will be written to
|
||
the path specified by \fB--snapshot-blob\fR.
|
||
.Bd -literal
|
||
$ 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
|
||
.Ed
|
||
The \fBv8.startupSnapshot\fR 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:
|
||
.Bd -literal
|
||
$ 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
|
||
.Ed
|
||
For more information, check out the \fBv8.startupSnapshot\fR API documentation.
|
||
The snapshot currently only supports loding 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 \fBv8.startupSnapshot.setDeserializeMainFunction()\fR or
|
||
\fBv8.startupSnapshot.addDeserializeCallback()\fR. 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.
|
||
.
|
||
.It Fl -build-snapshot-config
|
||
Specifies the path to a JSON configuration file which configures snapshot
|
||
creation behavior.
|
||
The following options are currently supported:
|
||
.Bl -bullet
|
||
.It
|
||
\fBbuilder\fR \fB<string>\fR Required. Provides the name to the script that is executed
|
||
before building the snapshot, as if \fB--build-snapshot\fR had been passed
|
||
with \fBbuilder\fR as the main script name.
|
||
.It
|
||
\fBwithoutCodeCache\fR \fB<boolean>\fR 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.
|
||
.El
|
||
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.
|
||
.
|
||
.It Fl c , Fl -check
|
||
Syntax check the script without executing.
|
||
.
|
||
.It Fl -completion-bash
|
||
Print source-able bash completion script for Node.js.
|
||
.Bd -literal
|
||
node --completion-bash > node_bash_completion
|
||
source node_bash_completion
|
||
.Ed
|
||
.
|
||
.It Fl C Ar condition , Fl -conditions Ns = Ns Ar condition
|
||
Provide custom conditional exports resolution conditions.
|
||
Any number of custom string condition names are permitted.
|
||
The default Node.js conditions of \fB"node"\fR, \fB"default"\fR, \fB"import"\fR, and
|
||
\fB"require"\fR will always apply as defined.
|
||
For example, to run a module with "development" resolutions:
|
||
.Bd -literal
|
||
node -C development app.js
|
||
.Ed
|
||
.
|
||
.It Fl -cpu-prof
|
||
Starts the V8 CPU profiler on start up, and writes the CPU profile to disk
|
||
before exit.
|
||
If \fB--cpu-prof-dir\fR is not specified, the generated profile is placed
|
||
in the current working directory.
|
||
If \fB--cpu-prof-name\fR is not specified, the generated profile is
|
||
named \fBCPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile\fR.
|
||
.Bd -literal
|
||
$ node --cpu-prof index.js
|
||
$ ls *.cpuprofile
|
||
CPU.20190409.202950.15293.0.0.cpuprofile
|
||
.Ed
|
||
If \fB--cpu-prof-name\fR 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:
|
||
.Bl -bullet
|
||
.It
|
||
\fB${pid}\fR — the current process ID
|
||
.El
|
||
.Bd -literal
|
||
$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
|
||
$ ls *.cpuprofile
|
||
CPU.15293.cpuprofile
|
||
.Ed
|
||
.
|
||
.It Fl -cpu-prof-dir
|
||
Specify the directory where the CPU profiles generated by \fB--cpu-prof\fR will
|
||
be placed.
|
||
The default value is controlled by the
|
||
\fB--diagnostic-dir\fR command-line option.
|
||
.
|
||
.It Fl -cpu-prof-interval
|
||
Specify the sampling interval in microseconds for the CPU profiles generated
|
||
by \fB--cpu-prof\fR. The default is 1000 microseconds.
|
||
.
|
||
.It Fl -cpu-prof-name
|
||
Specify the file name of the CPU profile generated by \fB--cpu-prof\fR.
|
||
.
|
||
.It Fl -diagnostic-dir Ns = Ns Ar directory
|
||
Set the directory to which all diagnostic output files are written.
|
||
Defaults to current working directory.
|
||
Affects the default output directory of:
|
||
.Bl -bullet
|
||
.It
|
||
\fB--cpu-prof-dir\fR
|
||
.It
|
||
\fB--heap-prof-dir\fR
|
||
.It
|
||
\fB--redirect-warnings\fR
|
||
.El
|
||
.
|
||
.It Fl -disable-proto Ns = Ns Ar mode
|
||
Disable the \fBObject.prototype.__proto__\fR property. If \fBmode\fR is \fBdelete\fR, the
|
||
property is removed entirely. If \fBmode\fR is \fBthrow\fR, accesses to the
|
||
property throw an exception with the code \fBERR_PROTO_ACCESS\fR.
|
||
.
|
||
.It Fl -disable-sigusr1
|
||
Disable the ability of starting a debugging session by sending a
|
||
\fBSIGUSR1\fR signal to the process.
|
||
.
|
||
.It Fl -disable-warning Ns = Ns Ar code-or-type
|
||
Disable specific process warnings by \fBcode\fR or \fBtype\fR.
|
||
Warnings emitted from \fBprocess.emitWarning()\fR may contain a
|
||
\fBcode\fR and a \fBtype\fR. This option will not-emit warnings that have a matching
|
||
\fBcode\fR or \fBtype\fR.
|
||
List of deprecation warnings.
|
||
The Node.js core warning types are: \fBDeprecationWarning\fR and
|
||
\fBExperimentalWarning\fR
|
||
For example, the following script will not emit
|
||
DEP0025 \fBrequire('node:sys')\fR when executed with
|
||
\fBnode --disable-warning=DEP0025\fR:
|
||
.Bd -literal
|
||
import sys from 'node:sys';
|
||
.Ed
|
||
.Bd -literal
|
||
const sys = require('node:sys');
|
||
.Ed
|
||
For example, the following script will emit the
|
||
DEP0025 \fBrequire('node:sys')\fR, but not any Experimental
|
||
Warnings (such as
|
||
ExperimentalWarning: \fBvm.measureMemory\fR is an experimental feature
|
||
in <=v21) when executed with \fBnode --disable-warning=ExperimentalWarning\fR:
|
||
.Bd -literal
|
||
import sys from 'node:sys';
|
||
import vm from 'node:vm';
|
||
|
||
vm.measureMemory();
|
||
.Ed
|
||
.Bd -literal
|
||
const sys = require('node:sys');
|
||
const vm = require('node:vm');
|
||
|
||
vm.measureMemory();
|
||
.Ed
|
||
.
|
||
.It Fl -disable-wasm-trap-handler
|
||
By default, Node.js enables trap-handler-based WebAssembly bound
|
||
checks. As a result, V8 does not need to insert inline bound checks
|
||
in the code compiled from WebAssembly which may speed up WebAssembly
|
||
execution significantly, but this optimization requires allocating
|
||
a big virtual memory cage (currently 10GB). If the Node.js process
|
||
does not have access to a large enough virtual memory address space
|
||
due to system configurations or hardware limitations, users won't
|
||
be able to run any WebAssembly that involves allocation in this
|
||
virtual memory cage and will see an out-of-memory error.
|
||
.Bd -literal
|
||
$ ulimit -v 5000000
|
||
$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"
|
||
[eval]:1
|
||
new WebAssembly.Memory({ initial: 10, maximum: 100 });
|
||
^
|
||
|
||
RangeError: WebAssembly.Memory(): could not allocate memory
|
||
at [eval]:1:1
|
||
at runScriptInThisContext (node:internal/vm:209:10)
|
||
at node:internal/process/execution:118:14
|
||
at [eval]-wrapper:6:24
|
||
at runScript (node:internal/process/execution:101:62)
|
||
at evalScript (node:internal/process/execution:136:3)
|
||
at node:internal/main/eval_string:49:3
|
||
|
||
.Ed
|
||
\fB--disable-wasm-trap-handler\fR disables this optimization so that
|
||
users can at least run WebAssembly (with less optimal performance)
|
||
when the virtual memory address space available to their Node.js
|
||
process is lower than what the V8 WebAssembly memory cage needs.
|
||
.
|
||
.It Fl -disallow-code-generation-from-strings
|
||
Make built-in language features like \fBeval\fR and \fBnew Function\fR that generate
|
||
code from strings throw an exception instead. This does not affect the Node.js
|
||
\fBnode:vm\fR module.
|
||
.
|
||
.It Fl -dns-result-order Ns = Ns Ar order
|
||
Set the default value of \fBorder\fR in \fBdns.lookup()\fR and
|
||
\fBdnsPromises.lookup()\fR. The value could be:
|
||
.Bl -bullet
|
||
.It
|
||
\fBipv4first\fR: sets default \fBorder\fR to \fBipv4first\fR.
|
||
.It
|
||
\fBipv6first\fR: sets default \fBorder\fR to \fBipv6first\fR.
|
||
.It
|
||
\fBverbatim\fR: sets default \fBorder\fR to \fBverbatim\fR.
|
||
.El
|
||
The default is \fBverbatim\fR and \fBdns.setDefaultResultOrder()\fR have higher
|
||
priority than \fB--dns-result-order\fR.
|
||
.
|
||
.It Fl -enable-fips
|
||
Enable FIPS-compliant crypto at startup. (Requires Node.js to be built
|
||
against FIPS-compatible OpenSSL.)
|
||
.
|
||
.It Fl -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.
|
||
\fB--enable-source-maps\fR enables caching of Source Maps and makes a best
|
||
effort to report stack traces relative to the original source file.
|
||
Overriding \fBError.prepareStackTrace\fR may prevent \fB--enable-source-maps\fR from
|
||
modifying the stack trace. Call and return the results of the original
|
||
\fBError.prepareStackTrace\fR in the overriding function to modify the stack trace
|
||
with source maps.
|
||
.Bd -literal
|
||
const originalPrepareStackTrace = Error.prepareStackTrace;
|
||
Error.prepareStackTrace = (error, trace) => {
|
||
// Modify error and trace and format stack trace with
|
||
// original Error.prepareStackTrace.
|
||
return originalPrepareStackTrace(error, trace);
|
||
};
|
||
.Ed
|
||
Note, enabling source maps can introduce latency to your application
|
||
when \fBError.stack\fR is accessed. If you access \fBError.stack\fR frequently
|
||
in your application, take into account the performance implications
|
||
of \fB--enable-source-maps\fR.
|
||
.
|
||
.It Fl -entry-url
|
||
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 \fBimport.meta.url\fR.
|
||
.Bd -literal
|
||
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")'
|
||
.Ed
|
||
.
|
||
.It Fl -env-file-if-exists Ns = Ns Ar file
|
||
Behavior is the same as \fB--env-file\fR, but an error is not thrown if the file
|
||
does not exist.
|
||
.
|
||
.It Fl -env-file Ns = Ns Ar file
|
||
Loads environment variables from a file relative to the current directory,
|
||
making them available to applications on \fBprocess.env\fR. The environment
|
||
variables which configure Node.js, such as \fBNODE_OPTIONS\fR,
|
||
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 \fB--env-file\fR arguments. Subsequent files override
|
||
pre-existing variables defined in previous files.
|
||
An error is thrown if the file does not exist.
|
||
.Bd -literal
|
||
node --env-file=.env --env-file=.development.env index.js
|
||
.Ed
|
||
The format of the file should be one line per key-value pair of environment
|
||
variable name and value separated by \fB=\fR:
|
||
.Bd -literal
|
||
PORT=3000
|
||
.Ed
|
||
Any text after a \fB#\fR is treated as a comment:
|
||
.Bd -literal
|
||
# This is a comment
|
||
PORT=3000 # This is also a comment
|
||
.Ed
|
||
Values can start and end with the following quotes: \fB`\fR, \fB"\fR or \fB'\fR.
|
||
They are omitted from the values.
|
||
.Bd -literal
|
||
USERNAME="nodejs" # will result in `nodejs` as the value.
|
||
.Ed
|
||
Multi-line values are supported:
|
||
.Bd -literal
|
||
MULTI_LINE="THIS IS
|
||
A MULTILINE"
|
||
# will result in `THIS IS\\nA MULTILINE` as the value.
|
||
.Ed
|
||
Export keyword before a key is ignored:
|
||
.Bd -literal
|
||
export USERNAME="nodejs" # will result in `nodejs` as the value.
|
||
.Ed
|
||
If you want to load environment variables from a file that may not exist, you
|
||
can use the \fB--env-file-if-exists\fR flag instead.
|
||
.
|
||
.It Fl e , Fl -eval Ar "script"
|
||
Evaluate the following argument as JavaScript. The modules which are
|
||
predefined in the REPL can also be used in \fBscript\fR.
|
||
On Windows, using \fBcmd.exe\fR a single quote will not work correctly because it
|
||
only recognizes double \fB"\fR for quoting. In Powershell or Git bash, both \fB'\fR
|
||
and \fB"\fR are usable.
|
||
It is possible to run code containing inline types unless the
|
||
\fB--no-strip-types\fR flag is provided.
|
||
.
|
||
.It Fl -experimental-addon-modules
|
||
Enable experimental import support for \fB.node\fR addons.
|
||
.
|
||
.It Fl -experimental-config-file Ns = Ns Ar config
|
||
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. \fBvX.Y.Z\fR
|
||
in the \fB$schema\fR must be replaced with the version of Node.js you are using.
|
||
.Bd -literal
|
||
{
|
||
"$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
|
||
}
|
||
}
|
||
.Ed
|
||
The configuration file supports namespace-specific options:
|
||
.Bl -bullet
|
||
.It
|
||
The \fBnodeOptions\fR field contains CLI flags that are allowed in \fBNODE_OPTIONS\fR.
|
||
.It
|
||
Namespace fields like \fBtest\fR, \fBwatch\fR, and \fBpermission\fR contain configuration specific to that subsystem.
|
||
.El
|
||
When a namespace is present in the
|
||
configuration file, Node.js automatically enables the corresponding flag
|
||
(e.g., \fB--test\fR, \fB--watch\fR, \fB--permission\fR). This allows you to configure
|
||
subsystem-specific options without explicitly passing the flag on the command line.
|
||
For example:
|
||
.Bd -literal
|
||
{
|
||
"test": {
|
||
"test-isolation": "process"
|
||
}
|
||
}
|
||
.Ed
|
||
is equivalent to:
|
||
.Bd -literal
|
||
node --test --test-isolation=process
|
||
.Ed
|
||
To disable the automatic flag while still using namespace options, you can
|
||
explicitly set the flag to \fBfalse\fR within the namespace:
|
||
.Bd -literal
|
||
{
|
||
"test": {
|
||
"test": false,
|
||
"test-isolation": "process"
|
||
}
|
||
}
|
||
.Ed
|
||
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:
|
||
.Bd -literal
|
||
node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
|
||
.Ed
|
||
The priority in configuration is as follows:
|
||
.Bl -bullet
|
||
.It
|
||
NODE_OPTIONS and command-line options
|
||
.It
|
||
Configuration file
|
||
.It
|
||
Dotenv NODE_OPTIONS
|
||
.El
|
||
Values in the configuration file will not override the values in the environment
|
||
variables and command-line options, but will override the values in the \fBNODE_OPTIONS\fR
|
||
env file parsed by the \fB--env-file\fR 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 \fBNEVER\fR use untrusted configuration files.
|
||
.
|
||
.It Fl -experimental-default-config-file
|
||
If the \fB--experimental-default-config-file\fR flag is present, Node.js will look for a
|
||
\fBnode.config.json\fR file in the current working directory and load it as a
|
||
as configuration file.
|
||
.
|
||
.It Fl -experimental-eventsource
|
||
Enable exposition of EventSource Web API on the global scope.
|
||
.
|
||
.It Fl -experimental-import-meta-resolve
|
||
Enable experimental \fBimport.meta.resolve()\fR parent URL support, which allows
|
||
passing a second \fBparentURL\fR argument for contextual resolution.
|
||
Previously gated the entire \fBimport.meta.resolve\fR feature.
|
||
.
|
||
.It Fl -experimental-inspector-network-resource
|
||
Enable experimental support for inspector network resources.
|
||
.
|
||
.It Fl -experimental-loader Ns = Ns Ar module
|
||
Specify the \fBmodule\fR containing exported asynchronous module customization hooks.
|
||
\fBmodule\fR may be any string accepted as an \fBimport\fR specifier.
|
||
This feature requires \fB--allow-worker\fR if used with the Permission Model.
|
||
.
|
||
.It Fl -experimental-network-inspection
|
||
Enable experimental support for the network inspection with Chrome DevTools.
|
||
.
|
||
.It Fl -experimental-print-required-tla
|
||
If the ES module being \fBrequire()\fR'd contains top-level \fBawait\fR, this flag
|
||
allows Node.js to evaluate the module, try to locate the
|
||
top-level awaits, and print their location to help users find them.
|
||
.
|
||
.It Fl -experimental-quic
|
||
Enable experimental support for the QUIC protocol.
|
||
.
|
||
.It Fl -experimental-stream-iter
|
||
Enable the experimental
|
||
.Sy node:stream/iter
|
||
module.
|
||
.
|
||
.It Fl -experimental-sea-config
|
||
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.
|
||
.
|
||
.It Fl -experimental-shadow-realm
|
||
Use this flag to enable ShadowRealm support.
|
||
.
|
||
.It Fl -experimental-storage-inspection
|
||
Enable experimental support for storage inspection
|
||
.
|
||
.It Fl -experimental-test-coverage
|
||
When used in conjunction with the \fBnode:test\fR 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.
|
||
.
|
||
.It Fl -experimental-test-module-mocks
|
||
Enable module mocking in the test runner.
|
||
This feature requires \fB--allow-worker\fR if used with the Permission Model.
|
||
.
|
||
.It Fl -experimental-vm-modules
|
||
Enable experimental ES Module support in the \fBnode:vm\fR module.
|
||
.
|
||
.It Fl -experimental-wasi-unstable-preview1
|
||
Enable experimental WebAssembly System Interface (WASI) support.
|
||
.
|
||
.It Fl -experimental-worker-inspection
|
||
Enable experimental support for the worker inspection with Chrome DevTools.
|
||
.
|
||
.It Fl -expose-gc
|
||
This flag will expose the gc extension from V8.
|
||
.Bd -literal
|
||
if (globalThis.gc) {
|
||
globalThis.gc();
|
||
}
|
||
.Ed
|
||
.
|
||
.It Fl -force-context-aware
|
||
Disable loading native addons that are not context-aware.
|
||
.
|
||
.It Fl -force-fips
|
||
Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.)
|
||
(Same requirements as \fB--enable-fips\fR.)
|
||
.
|
||
.It Fl -force-node-api-uncaught-exceptions-policy
|
||
Enforces \fBuncaughtException\fR 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.
|
||
.
|
||
.It Fl -frozen-intrinsics
|
||
Enable experimental frozen intrinsics like \fBArray\fR and \fBObject\fR.
|
||
Only the root context is supported. There is no guarantee that
|
||
\fBglobalThis.Array\fR is indeed the default intrinsic reference. Code may break
|
||
under this flag.
|
||
To allow polyfills to be added,
|
||
\fB--require\fR and \fB--import\fR both run before freezing intrinsics.
|
||
.
|
||
.It Fl -heap-prof
|
||
Starts the V8 heap profiler on start up, and writes the heap profile to disk
|
||
before exit.
|
||
If \fB--heap-prof-dir\fR is not specified, the generated profile is placed
|
||
in the current working directory.
|
||
If \fB--heap-prof-name\fR is not specified, the generated profile is
|
||
named \fBHeap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile\fR.
|
||
.Bd -literal
|
||
$ node --heap-prof index.js
|
||
$ ls *.heapprofile
|
||
Heap.20190409.202950.15293.0.001.heapprofile
|
||
.Ed
|
||
.
|
||
.It Fl -heap-prof-dir
|
||
Specify the directory where the heap profiles generated by \fB--heap-prof\fR will
|
||
be placed.
|
||
The default value is controlled by the
|
||
\fB--diagnostic-dir\fR command-line option.
|
||
.
|
||
.It Fl -heap-prof-interval
|
||
Specify the average sampling interval in bytes for the heap profiles generated
|
||
by \fB--heap-prof\fR. The default is 512 * 1024 bytes.
|
||
.
|
||
.It Fl -heap-prof-name
|
||
Specify the file name of the heap profile generated by \fB--heap-prof\fR.
|
||
.
|
||
.It Fl -heapsnapshot-near-heap-limit Ns = Ns Ar max_count
|
||
Writes a V8 heap snapshot to disk when the V8 heap usage is approaching the
|
||
heap limit. \fBcount\fR should be a non-negative integer (in which case
|
||
Node.js will write no more than \fBmax_count\fR snapshots to disk).
|
||
When generating snapshots, garbage collection may be triggered and bring
|
||
the heap usage down. Therefore multiple snapshots may be written to disk
|
||
before the Node.js instance finally runs out of memory. These heap snapshots
|
||
can be compared to determine what objects are being allocated during the
|
||
time consecutive snapshots are taken. It's not guaranteed that Node.js will
|
||
write exactly \fBmax_count\fR snapshots to disk, but it will try
|
||
its best to generate at least one and up to \fBmax_count\fR snapshots before the
|
||
Node.js instance runs out of memory when \fBmax_count\fR is greater than \fB0\fR.
|
||
Generating V8 snapshots takes time and memory (both memory managed by the
|
||
V8 heap and native memory outside the V8 heap). The bigger the heap is,
|
||
the more resources it needs. Node.js will adjust the V8 heap to accommodate
|
||
the additional V8 heap memory overhead, and try its best to avoid using up
|
||
all the memory available to the process. When the process uses
|
||
more memory than the system deems appropriate, the process may be terminated
|
||
abruptly by the system, depending on the system configuration.
|
||
.Bd -literal
|
||
$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js
|
||
Wrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot
|
||
Wrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot
|
||
Wrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot
|
||
|
||
<--- Last few GCs --->
|
||
|
||
[49580:0x110000000] 4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed
|
||
[49580:0x110000000] 4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed
|
||
|
||
|
||
<--- JS stacktrace --->
|
||
|
||
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
|
||
....
|
||
.Ed
|
||
.
|
||
.It Fl -heapsnapshot-signal Ns = Ns Ar signal
|
||
Enables a signal handler that causes the Node.js process to write a heap dump
|
||
when the specified signal is received. \fBsignal\fR must be a valid signal name.
|
||
Disabled by default.
|
||
.Bd -literal
|
||
$ node --heapsnapshot-signal=SIGUSR2 index.js &
|
||
$ ps aux
|
||
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
|
||
node 1 5.5 6.1 787252 247004 ? Ssl 16:43 0:02 node --heapsnapshot-signal=SIGUSR2 index.js
|
||
$ kill -USR2 1
|
||
$ ls
|
||
Heap.20190718.133405.15554.0.001.heapsnapshot
|
||
.Ed
|
||
.
|
||
.It Fl h , Fl -help
|
||
Print node command-line options.
|
||
The output of this option is less detailed than this document.
|
||
.
|
||
.It Fl -icu-data-dir Ns = Ns Ar file
|
||
Specify ICU data load path. (Overrides \fBNODE_ICU_DATA\fR.)
|
||
.
|
||
.It Fl -import Ns = Ns Ar module
|
||
Preload the specified module at startup. If the flag is provided several times,
|
||
each module will be executed sequentially in the order they appear, starting
|
||
with the ones provided in \fBNODE_OPTIONS\fR.
|
||
Follows ECMAScript module resolution rules.
|
||
Use \fB--require\fR to load a CommonJS module.
|
||
Modules preloaded with \fB--require\fR will run before modules preloaded with \fB--import\fR.
|
||
Modules are preloaded into the main thread as well as any worker threads,
|
||
forked processes, or clustered processes.
|
||
.
|
||
.It Fl -input-type Ns = Ns Ar type
|
||
This configures Node.js to interpret \fB--eval\fR or \fBSTDIN\fR input as CommonJS or
|
||
as an ES module. Valid values are \fB"commonjs"\fR, \fB"module"\fR, \fB"module-typescript"\fR and \fB"commonjs-typescript"\fR.
|
||
The \fB"-typescript"\fR values are not available with the flag \fB--no-strip-types\fR.
|
||
The default is no value, or \fB"commonjs"\fR if \fB--no-experimental-detect-module\fR is passed.
|
||
If \fB--input-type\fR is not provided,
|
||
Node.js will try to detect the syntax with the following steps:
|
||
.Bl -bullet
|
||
.It
|
||
Run the input as CommonJS.
|
||
.It
|
||
If step 1 fails, run the input as an ES module.
|
||
.It
|
||
If step 2 fails with a SyntaxError, strip the types.
|
||
.It
|
||
If step 3 fails with an error code \fBERR_UNSUPPORTED_TYPESCRIPT_SYNTAX\fR
|
||
or \fBERR_INVALID_TYPESCRIPT_SYNTAX\fR,
|
||
throw the error from step 2, including the TypeScript error in the message,
|
||
else run as CommonJS.
|
||
.It
|
||
If step 4 fails, run the input as an ES module.
|
||
.El
|
||
To avoid the delay of multiple syntax detection passes, the \fB--input-type=type\fR flag can be used to specify
|
||
how the \fB--eval\fR input should be interpreted.
|
||
The REPL does not support this option. Usage of \fB--input-type=module\fR with
|
||
\fB--print\fR will throw an error, as \fB--print\fR does not support ES module
|
||
syntax.
|
||
.
|
||
.It Fl -insecure-http-parser
|
||
Enable leniency flags on the HTTP parser. This may allow
|
||
interoperability with non-conformant HTTP implementations.
|
||
When enabled, the parser will accept the following:
|
||
.Bl -bullet
|
||
.It
|
||
Invalid HTTP headers values.
|
||
.It
|
||
Invalid HTTP versions.
|
||
.It
|
||
Allow message containing both \fBTransfer-Encoding\fR
|
||
and \fBContent-Length\fR headers.
|
||
.It
|
||
Allow extra data after message when \fBConnection: close\fR is present.
|
||
.It
|
||
Allow extra transfer encodings after \fBchunked\fR has been provided.
|
||
.It
|
||
Allow \fB\\n\fR to be used as token separator instead of \fB\\r\\n\fR.
|
||
.It
|
||
Allow \fB\\r\\n\fR not to be provided after a chunk.
|
||
.It
|
||
Allow spaces to be present after a chunk size and before \fB\\r\\n\fR.
|
||
.El
|
||
All the above will expose your application to request smuggling
|
||
or poisoning attack. Avoid using this option.
|
||
.
|
||
.It Fl -inspect-brk Ns = Ns Ar [[host:]port]
|
||
Activate inspector on \fBhost:port\fR and break at start of user script.
|
||
Default \fBhost:port\fR is \fB127.0.0.1:9229\fR. If port \fB0\fR is specified,
|
||
a random available port will be used.
|
||
See V8 Inspector integration for Node.js for further explanation on Node.js debugger.
|
||
.
|
||
.It Fl -inspect-port Ns = Ns Ar [host:]port
|
||
Set the \fBhost:port\fR to be used when the inspector is activated.
|
||
Useful when activating the inspector by sending the \fBSIGUSR1\fR signal.
|
||
Except when \fB--disable-sigusr1\fR is passed.
|
||
Default host is \fB127.0.0.1\fR. If port \fB0\fR is specified,
|
||
a random available port will be used.
|
||
See the security warning below regarding the \fBhost\fR
|
||
parameter usage.
|
||
.
|
||
.It Fl -inspect-publish-uid Ns = Ns Ar stderr,http
|
||
Specify ways of the inspector web socket url exposure.
|
||
By default inspector websocket url is available in stderr and under \fB/json/list\fR
|
||
endpoint on \fBhttp://host:port/json/list\fR.
|
||
.
|
||
.It Fl -inspect-wait Ns = Ns Ar [[host:]port]
|
||
Activate inspector on \fBhost:port\fR and wait for debugger to be attached.
|
||
Default \fBhost:port\fR is \fB127.0.0.1:9229\fR. If port \fB0\fR is specified,
|
||
a random available port will be used.
|
||
See V8 Inspector integration for Node.js for further explanation on Node.js debugger.
|
||
.
|
||
.It Fl -inspect Ns = Ns Ar [[host:]port]
|
||
Activate inspector on \fBhost:port\fR. Default is \fB127.0.0.1:9229\fR. If port \fB0\fR is
|
||
specified, a random available port will be used.
|
||
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug
|
||
and profile Node.js instances. The tools attach to Node.js instances via a
|
||
tcp port and communicate using the Chrome DevTools Protocol.
|
||
See V8 Inspector integration for Node.js for further explanation on Node.js debugger.
|
||
.
|
||
.It Fl i , Fl -interactive
|
||
Opens the REPL even if stdin does not appear to be a terminal.
|
||
.
|
||
.It Fl -jitless
|
||
Disable runtime allocation of executable memory. This may be
|
||
required on some platforms for security reasons. It can also reduce attack
|
||
surface on other platforms, but the performance impact may be severe.
|
||
.
|
||
.It Fl -localstorage-file Ns = Ns Ar file
|
||
The file used to store \fBlocalStorage\fR data. If the file does not exist, it is
|
||
created the first time \fBlocalStorage\fR is accessed. The same file may be shared
|
||
between multiple Node.js processes concurrently.
|
||
.
|
||
.It Fl -max-http-header-size Ns = Ns Ar size
|
||
Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB.
|
||
.
|
||
.It Fl -max-old-space-size-percentage Ns = Ns Ar percentage
|
||
Sets the maximum memory size of V8's old memory section as a percentage of available system memory.
|
||
This flag takes precedence over \fB--max-old-space-size\fR when both are specified.
|
||
The \fBpercentage\fR parameter must be a number greater than 0 and up to 100, representing the percentage
|
||
of available system memory to allocate to the V8 heap.
|
||
\fBNote:\fR This flag utilizes \fB--max-old-space-size\fR, which may be unreliable on 32-bit platforms due to
|
||
integer overflow issues.
|
||
.Bd -literal
|
||
# Using 50% of available system memory
|
||
node --max-old-space-size-percentage=50 index.js
|
||
|
||
# Using 75% of available system memory
|
||
node --max-old-space-size-percentage=75 index.js
|
||
.Ed
|
||
.
|
||
.It Fl -napi-modules
|
||
This option is a no-op. It is kept for compatibility.
|
||
.
|
||
.It Fl -network-family-autoselection-attempt-timeout
|
||
Sets the default value for the network family autoselection attempt timeout.
|
||
For more information, see \fBnet.getDefaultAutoSelectFamilyAttemptTimeout()\fR.
|
||
.
|
||
.It Fl -no-addons
|
||
Disable the \fBnode-addons\fR exports condition as well as disable loading
|
||
native addons. When \fB--no-addons\fR is specified, calling \fBprocess.dlopen\fR or
|
||
requiring a native C++ addon will fail and throw an exception.
|
||
.
|
||
.It Fl -no-async-context-frame
|
||
Disables the use of \fBAsyncLocalStorage\fR backed by \fBAsyncContextFrame\fR and
|
||
uses the prior implementation which relied on async_hooks. The previous model
|
||
is retained for compatibility with Electron and for cases where the context
|
||
flow may differ. However, if a difference in flow is found please report it.
|
||
.
|
||
.It Fl -no-deprecation
|
||
Silence deprecation warnings.
|
||
.
|
||
.It Fl -no-experimental-detect-module
|
||
Disable using syntax detection to determine module type.
|
||
.
|
||
.It Fl -no-experimental-global-navigator
|
||
Disable exposition of Navigator API on the global scope.
|
||
.
|
||
.It Fl -no-experimental-repl-await
|
||
Use this flag to disable top-level await in REPL.
|
||
.
|
||
.It Fl -no-experimental-require-module
|
||
Legacy alias for \fB--no-require-module\fR.
|
||
.
|
||
.It Fl -no-experimental-sqlite
|
||
Disable the experimental \fBnode:sqlite\fR module.
|
||
.
|
||
.It Fl -no-experimental-websocket
|
||
Disable exposition of \fB<WebSocket>\fR on the global scope.
|
||
.
|
||
.It Fl -no-experimental-webstorage
|
||
Disable \fBWeb Storage\fR support.
|
||
.
|
||
.It Fl -no-extra-info-on-fatal-exception
|
||
Hide extra information on fatal exception that causes exit.
|
||
.
|
||
.It Fl -no-force-async-hooks-checks
|
||
Disables runtime checks for \fBasync_hooks\fR. These will still be enabled
|
||
dynamically when \fBasync_hooks\fR is enabled.
|
||
.
|
||
.It Fl -no-global-search-paths
|
||
Do not search modules from global paths like \fB$HOME/.node_modules\fR and
|
||
\fB$NODE_PATH\fR.
|
||
.
|
||
.It Fl -no-network-family-autoselection
|
||
Disables the family autoselection algorithm unless connection options explicitly
|
||
enables it.
|
||
.
|
||
.It Fl -no-require-module
|
||
Disable support for loading a synchronous ES module graph in \fBrequire()\fR.
|
||
See Loading ECMAScript modules using \fBrequire()\fR.
|
||
.
|
||
.It Fl -no-strip-types
|
||
Disable type-stripping for TypeScript files.
|
||
For more information, see the TypeScript type-stripping documentation.
|
||
.
|
||
.It Fl -no-warnings
|
||
Silence all process warnings (including deprecations).
|
||
.
|
||
.It Fl -node-memory-debug
|
||
Enable extra debug checks for memory leaks in Node.js internals. This is
|
||
usually only useful for developers debugging Node.js itself.
|
||
.
|
||
.It Fl -openssl-config Ns = Ns Ar file
|
||
Load an OpenSSL configuration file on startup. Among other uses, this can be
|
||
used to enable FIPS-compliant crypto if Node.js is built
|
||
against FIPS-enabled OpenSSL.
|
||
.
|
||
.It Fl -openssl-legacy-provider
|
||
Enable OpenSSL 3.0 legacy provider. For more information please see
|
||
OSSL_PROVIDER-legacy.
|
||
.
|
||
.It Fl -openssl-shared-config
|
||
Enable OpenSSL default configuration section, \fBopenssl_conf\fR to be read from
|
||
the OpenSSL configuration file. The default configuration file is named
|
||
\fBopenssl.cnf\fR but this can be changed using the environment variable
|
||
\fBOPENSSL_CONF\fR, or by using the command line option \fB--openssl-config\fR.
|
||
The location of the default OpenSSL configuration file depends on how OpenSSL
|
||
is being linked to Node.js. Sharing the OpenSSL configuration may have unwanted
|
||
implications and it is recommended to use a configuration section specific to
|
||
Node.js which is \fBnodejs_conf\fR and is default when this option is not used.
|
||
.
|
||
.It Fl -pending-deprecation
|
||
Emit pending deprecation warnings.
|
||
Pending deprecations are generally identical to a runtime deprecation with the
|
||
notable exception that they are turned \fIoff\fR by default and will not be emitted
|
||
unless either the \fB--pending-deprecation\fR command-line flag, or the
|
||
\fBNODE_PENDING_DEPRECATION=1\fR environment variable, is set. Pending deprecations
|
||
are used to provide a kind of selective "early warning" mechanism that
|
||
developers may leverage to detect deprecated API usage.
|
||
.
|
||
.It Fl -permission
|
||
Enable the Permission Model for current process. When enabled, the
|
||
following permissions are restricted:
|
||
.Bl -bullet
|
||
.It
|
||
File System - manageable through
|
||
\fB--allow-fs-read\fR, \fB--allow-fs-write\fR flags
|
||
.It
|
||
Network - manageable through \fB--allow-net\fR flag
|
||
.It
|
||
Child Process - manageable through \fB--allow-child-process\fR flag
|
||
.It
|
||
Worker Threads - manageable through \fB--allow-worker\fR flag
|
||
.It
|
||
WASI - manageable through \fB--allow-wasi\fR flag
|
||
.It
|
||
Addons - manageable through \fB--allow-addons\fR flag
|
||
.El
|
||
.
|
||
.It Fl -permission-audit
|
||
Enable audit only for the permission model. When enabled, permission checks
|
||
are performed but access is not denied. Instead, a warning is emitted for
|
||
each permission violation via diagnostics channel.
|
||
.
|
||
.It Fl -preserve-symlinks
|
||
Instructs the module loader to preserve symbolic links when resolving and
|
||
caching modules.
|
||
By default, when Node.js loads a module from a path that is symbolically linked
|
||
to a different on-disk location, Node.js will dereference the link and use the
|
||
actual on-disk "real path" of the module as both an identifier and as a root
|
||
path to locate other dependency modules. In most cases, this default behavior
|
||
is acceptable. However, when using symbolically linked peer dependencies, as
|
||
illustrated in the example below, the default behavior causes an exception to
|
||
be thrown if \fBmoduleA\fR attempts to require \fBmoduleB\fR as a peer dependency:
|
||
.Bd -literal
|
||
{appDir}
|
||
├── app
|
||
│ ├── index.js
|
||
│ └── node_modules
|
||
│ ├── moduleA -> {appDir}/moduleA
|
||
│ └── moduleB
|
||
│ ├── index.js
|
||
│ └── package.json
|
||
└── moduleA
|
||
├── index.js
|
||
└── package.json
|
||
.Ed
|
||
The \fB--preserve-symlinks\fR command-line flag instructs Node.js to use the
|
||
symlink path for modules as opposed to the real path, allowing symbolically
|
||
linked peer dependencies to be found.
|
||
Note, however, that using \fB--preserve-symlinks\fR can have other side effects.
|
||
Specifically, symbolically linked \fInative\fR modules can fail to load if those
|
||
are linked from more than one location in the dependency tree (Node.js would
|
||
see those as two separate modules and would attempt to load the module multiple
|
||
times, causing an exception to be thrown).
|
||
The \fB--preserve-symlinks\fR flag does not apply to the main module, which allows
|
||
\fBnode --preserve-symlinks node_module/.bin/<foo>\fR to work. To apply the same
|
||
behavior for the main module, also use \fB--preserve-symlinks-main\fR.
|
||
.
|
||
.It Fl -preserve-symlinks-main
|
||
Instructs the module loader to preserve symbolic links when resolving and
|
||
caching the main module (\fBrequire.main\fR).
|
||
This flag exists so that the main module can be opted-in to the same behavior
|
||
that \fB--preserve-symlinks\fR gives to all other imports; they are separate flags,
|
||
however, for backward compatibility with older Node.js versions.
|
||
\fB--preserve-symlinks-main\fR does not imply \fB--preserve-symlinks\fR; use
|
||
\fB--preserve-symlinks-main\fR in addition to
|
||
\fB--preserve-symlinks\fR when it is not desirable to follow symlinks before
|
||
resolving relative paths.
|
||
See \fB--preserve-symlinks\fR for more information.
|
||
.
|
||
.It Fl p , Fl -print Ar "script"
|
||
Identical to \fB-e\fR but prints the result.
|
||
.
|
||
.It Fl -prof
|
||
Generate V8 profiler output.
|
||
.
|
||
.It Fl -prof-process
|
||
Process V8 profiler output generated using the V8 option \fB--prof\fR.
|
||
.
|
||
.It Fl -redirect-warnings Ns = Ns Ar file
|
||
Write process warnings to the given file instead of printing to stderr. The
|
||
file will be created if it does not exist, and will be appended to if it does.
|
||
If an error occurs while attempting to write the warning to the file, the
|
||
warning will be written to stderr instead.
|
||
The \fBfile\fR name may be an absolute path. If it is not, the default directory it
|
||
will be written to is controlled by the
|
||
\fB--diagnostic-dir\fR command-line option.
|
||
.
|
||
.It Fl -report-compact
|
||
Write reports in a compact format, single-line JSON, more easily consumable
|
||
by log processing systems than the default multi-line format designed for
|
||
human consumption.
|
||
.
|
||
.It Fl -report-dir Ns = Ns Ar directory , Fl -report-directory Ns = Ns Ar directory
|
||
Location at which the report will be generated.
|
||
.
|
||
.It Fl -report-exclude-env
|
||
When \fB--report-exclude-env\fR is passed the diagnostic report generated will not
|
||
contain the \fBenvironmentVariables\fR data.
|
||
.
|
||
.It Fl -report-exclude-network
|
||
Exclude \fBheader.networkInterfaces\fR from the diagnostic report. By default
|
||
this is not set and the network interfaces are included.
|
||
.
|
||
.It Fl -report-filename Ns = Ns Ar filename
|
||
Name of the file to which the report will be written.
|
||
If the filename is set to \fB'stdout'\fR or \fB'stderr'\fR, the report is written to
|
||
the stdout or stderr of the process respectively.
|
||
.
|
||
.It Fl -report-on-fatalerror
|
||
Enables the report to be triggered on fatal errors (internal errors within
|
||
the Node.js runtime such as out of memory) that lead to termination of the
|
||
application. Useful to inspect various diagnostic data elements such as heap,
|
||
stack, event loop state, resource consumption etc. to reason about the fatal
|
||
error.
|
||
.
|
||
.It Fl -report-on-signal
|
||
Enables report to be generated upon receiving the specified (or predefined)
|
||
signal to the running Node.js process. The signal to trigger the report is
|
||
specified through \fB--report-signal\fR.
|
||
.
|
||
.It Fl -report-signal Ns = Ns Ar signal
|
||
Sets or resets the signal for report generation (not supported on Windows).
|
||
Default signal is \fBSIGUSR2\fR.
|
||
.
|
||
.It Fl -report-uncaught-exception
|
||
Enables report to be generated when the process exits due to an uncaught
|
||
exception. Useful when inspecting the JavaScript stack in conjunction with
|
||
native stack and other runtime environment data.
|
||
.
|
||
.It Fl r , Fl -require Ar module
|
||
Preload the specified module at startup.
|
||
Follows \fBrequire()\fR's module resolution
|
||
rules. \fBmodule\fR may be either a path to a file, or a node module name.
|
||
Modules preloaded with \fB--require\fR will run before modules preloaded with \fB--import\fR.
|
||
Modules are preloaded into the main thread as well as any worker threads,
|
||
forked processes, or clustered processes.
|
||
.
|
||
.It Fl -run
|
||
This runs a specified command from a package.json's \fB"scripts"\fR object.
|
||
If a missing \fB"command"\fR is provided, it will list the available scripts.
|
||
\fB--run\fR will traverse up to the root directory and finds a \fBpackage.json\fR
|
||
file to run the command from.
|
||
\fB--run\fR prepends \fB./node_modules/.bin\fR for each ancestor of
|
||
the current directory, to the \fBPATH\fR in order to execute the binaries from
|
||
different folders where multiple \fBnode_modules\fR directories are present, if
|
||
\fBancestor-folder/node_modules/.bin\fR is a directory.
|
||
\fB--run\fR executes the command in the directory containing the related \fBpackage.json\fR.
|
||
For example, the following command will run the \fBtest\fR script of
|
||
the \fBpackage.json\fR in the current folder:
|
||
.Bd -literal
|
||
$ node --run test
|
||
.Ed
|
||
You can also pass arguments to the command. Any argument after \fB--\fR will
|
||
be appended to the script:
|
||
.Bd -literal
|
||
$ node --run test -- --verbose
|
||
.Ed
|
||
.
|
||
.It Fl -secure-heap-min Ns = Ns Ar n
|
||
When using \fB--secure-heap\fR, the \fB--secure-heap-min\fR flag specifies the
|
||
minimum allocation from the secure heap. The minimum value is \fB2\fR.
|
||
The maximum value is the lesser of \fB--secure-heap\fR or \fB2147483647\fR.
|
||
The value given must be a power of two.
|
||
.
|
||
.It Fl -secure-heap Ns = Ns Ar n
|
||
Initializes an OpenSSL secure heap of \fBn\fR bytes. When initialized, the
|
||
secure heap is used for selected types of allocations within OpenSSL
|
||
during key generation and other operations. This is useful, for instance,
|
||
to prevent sensitive information from leaking due to pointer overruns
|
||
or underruns.
|
||
The secure heap is a fixed size and cannot be resized at runtime so,
|
||
if used, it is important to select a large enough heap to cover all
|
||
application uses.
|
||
The heap size given must be a power of two. Any value less than 2
|
||
will disable the secure heap.
|
||
The secure heap is disabled by default.
|
||
The secure heap is not available on Windows.
|
||
See \fBCRYPTO_secure_malloc_init\fR for more details.
|
||
.
|
||
.It Fl -snapshot-blob Ns = Ns Ar path
|
||
When used with \fB--build-snapshot\fR, \fB--snapshot-blob\fR specifies the path
|
||
where the generated snapshot blob is written to. If not specified, the
|
||
generated blob is written to \fBsnapshot.blob\fR in the current working directory.
|
||
When used without \fB--build-snapshot\fR, \fB--snapshot-blob\fR specifies the
|
||
path to the blob that is used to restore the application state.
|
||
When loading a snapshot, Node.js checks that:
|
||
.Bl -bullet
|
||
.It
|
||
The version, architecture, and platform of the running Node.js binary
|
||
are exactly the same as that of the binary that generates the snapshot.
|
||
.It
|
||
The V8 flags and CPU features are compatible with that of the binary
|
||
that generates the snapshot.
|
||
.El
|
||
If they don't match, Node.js refuses to load the snapshot and exits with
|
||
status code 1.
|
||
.
|
||
.It Fl -test
|
||
Starts the Node.js command line test runner. This flag cannot be combined with
|
||
\fB--watch-path\fR, \fB--check\fR, \fB--eval\fR, \fB--interactive\fR, or the inspector.
|
||
See the documentation on running tests from the command line
|
||
for more details.
|
||
.
|
||
.It Fl -test-concurrency
|
||
The maximum number of test files that the test runner CLI will execute
|
||
concurrently. If \fB--test-isolation\fR is set to \fB'none'\fR, this flag is ignored and
|
||
concurrency is one. Otherwise, concurrency defaults to
|
||
\fBos.availableParallelism() - 1\fR.
|
||
.
|
||
.It Fl -test-coverage-branches Ns = Ns Ar threshold
|
||
Require a minimum percent of covered branches. If code coverage does not reach
|
||
the threshold specified, the process will exit with code \fB1\fR.
|
||
.
|
||
.It Fl -test-coverage-exclude
|
||
Excludes specific files from code coverage using a glob pattern, which can match
|
||
both absolute and relative file paths.
|
||
This option may be specified multiple times to exclude multiple glob patterns.
|
||
If both \fB--test-coverage-exclude\fR and \fB--test-coverage-include\fR are provided,
|
||
files must meet \fBboth\fR criteria to be included in the coverage report.
|
||
By default all the matching test files are excluded from the coverage report.
|
||
Specifying this option will override the default behavior.
|
||
.
|
||
.It Fl -test-coverage-functions Ns = Ns Ar threshold
|
||
Require a minimum percent of covered functions. If code coverage does not reach
|
||
the threshold specified, the process will exit with code \fB1\fR.
|
||
.
|
||
.It Fl -test-coverage-include
|
||
Includes specific files in code coverage using a glob pattern, which can match
|
||
both absolute and relative file paths.
|
||
This option may be specified multiple times to include multiple glob patterns.
|
||
If both \fB--test-coverage-exclude\fR and \fB--test-coverage-include\fR are provided,
|
||
files must meet \fBboth\fR criteria to be included in the coverage report.
|
||
.
|
||
.It Fl -test-coverage-lines Ns = Ns Ar threshold
|
||
Require a minimum percent of covered lines. If code coverage does not reach
|
||
the threshold specified, the process will exit with code \fB1\fR.
|
||
.
|
||
.It Fl -test-force-exit
|
||
Configures the test runner to exit the process once all known tests have
|
||
finished executing even if the event loop would otherwise remain active.
|
||
.
|
||
.It Fl -test-global-setup Ns = Ns Ar module
|
||
Specify a module that will be evaluated before all tests are executed and
|
||
can be used to setup global state or fixtures for tests.
|
||
See the documentation on global setup and teardown for more details.
|
||
.
|
||
.It Fl -test-isolation Ns = Ns Ar mode
|
||
Configures the type of test isolation used in the test runner. When \fBmode\fR is
|
||
\fB'process'\fR, each test file is run in a separate child process. When \fBmode\fR is
|
||
\fB'none'\fR, all test files run in the same process as the test runner. The default
|
||
isolation mode is \fB'process'\fR. This flag is ignored if the \fB--test\fR flag is not
|
||
present. See the test runner execution model section for more information.
|
||
.
|
||
.It Fl -test-name-pattern
|
||
A regular expression that configures the test runner to only execute tests
|
||
whose name matches the provided pattern. See the documentation on
|
||
filtering tests by name for more details.
|
||
If both \fB--test-name-pattern\fR and \fB--test-skip-pattern\fR are supplied,
|
||
tests must satisfy \fBboth\fR requirements in order to be executed.
|
||
.
|
||
.It Fl -test-only
|
||
Configures the test runner to only execute top level tests that have the \fBonly\fR
|
||
option set. This flag is not necessary when test isolation is disabled.
|
||
.
|
||
.It Fl -test-random-seed
|
||
Set the seed used to randomize test execution order.
|
||
This applies to both test file execution order and queued tests within each file.
|
||
Providing this flag enables randomization implicitly, even without
|
||
\fB--test-randomize\fR.
|
||
The value must be an integer between 0 and 4294967295.
|
||
This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR.
|
||
.
|
||
.It Fl -test-randomize
|
||
Randomize test execution order.
|
||
This applies to both test file execution order and queued tests within each file.
|
||
This can help detect tests that rely on shared state or execution order.
|
||
The seed used for randomization is printed in the test summary and can be
|
||
reused with \fB--test-random-seed\fR.
|
||
This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR.
|
||
.
|
||
.It Fl -test-reporter
|
||
A test reporter to use when running tests. See the documentation on
|
||
test reporters for more details.
|
||
.
|
||
.It Fl -test-reporter-destination
|
||
The destination for the corresponding test reporter. See the documentation on
|
||
test reporters for more details.
|
||
.
|
||
.It Fl -test-rerun-failures
|
||
A path to a file allowing the test runner to persist the state of the test
|
||
suite between runs. The test runner will use this file to determine which tests
|
||
have already succeeded or failed, allowing for re-running of failed tests
|
||
without having to re-run the entire test suite. The test runner will create this
|
||
file if it does not exist.
|
||
See the documentation on test reruns for more details.
|
||
.
|
||
.It Fl -test-shard
|
||
Test suite shard to execute in a format of \fB<index>/<total>\fR, where
|
||
.Bl -bullet
|
||
.It
|
||
\fBindex\fR is a positive integer, index of divided parts.
|
||
.It
|
||
\fBtotal\fR is a positive integer, total of divided part.
|
||
.El
|
||
This command will divide all tests files into \fBtotal\fR equal parts,
|
||
and will run only those that happen to be in an \fBindex\fR part.
|
||
For example, to split your tests suite into three parts, use this:
|
||
.Bd -literal
|
||
node --test --test-shard=1/3
|
||
node --test --test-shard=2/3
|
||
node --test --test-shard=3/3
|
||
.Ed
|
||
.
|
||
.It Fl -test-skip-pattern
|
||
A regular expression that configures the test runner to skip tests
|
||
whose name matches the provided pattern. See the documentation on
|
||
filtering tests by name for more details.
|
||
If both \fB--test-name-pattern\fR and \fB--test-skip-pattern\fR are supplied,
|
||
tests must satisfy \fBboth\fR requirements in order to be executed.
|
||
.
|
||
.It Fl -test-timeout
|
||
A number of milliseconds the test execution will fail after. If unspecified,
|
||
subtests inherit this value from their parent. The default value is \fBInfinity\fR.
|
||
.
|
||
.It Fl -test-update-snapshots
|
||
Regenerates the snapshot files used by the test runner for snapshot testing.
|
||
.
|
||
.It Fl -throw-deprecation
|
||
Throw errors for deprecations.
|
||
.
|
||
.It Fl -title Ns = Ns Ar title
|
||
Set \fBprocess.title\fR on startup.
|
||
.
|
||
.It Fl -tls-cipher-list Ns = Ns Ar list
|
||
Specify an alternative default TLS cipher list. Requires Node.js to be built
|
||
with crypto support (default).
|
||
.
|
||
.It Fl -tls-keylog Ns = Ns Ar file
|
||
Log TLS key material to a file. The key material is in NSS \fBSSLKEYLOGFILE\fR
|
||
format and can be used by software (such as Wireshark) to decrypt the TLS
|
||
traffic.
|
||
.
|
||
.It Fl -tls-max-v1.2
|
||
Set \fBtls.DEFAULT_MAX_VERSION\fR to 'TLSv1.2'. Use to disable support for
|
||
TLSv1.3.
|
||
.
|
||
.It Fl -tls-max-v1.3
|
||
Set default \fBtls.DEFAULT_MAX_VERSION\fR to 'TLSv1.3'. Use to enable support
|
||
for TLSv1.3.
|
||
.
|
||
.It Fl -tls-min-v1.0
|
||
Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1'. Use for compatibility with
|
||
old TLS clients or servers.
|
||
.
|
||
.It Fl -tls-min-v1.1
|
||
Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.1'. Use for compatibility
|
||
with old TLS clients or servers.
|
||
.
|
||
.It Fl -tls-min-v1.2
|
||
Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.2'. This is the default for
|
||
12.x and later, but the option is supported for compatibility with older Node.js
|
||
versions.
|
||
.
|
||
.It Fl -tls-min-v1.3
|
||
Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.3'. Use to disable support
|
||
for TLSv1.2, which is not as secure as TLSv1.3.
|
||
.
|
||
.It Fl -trace-deprecation
|
||
Print stack traces for deprecations.
|
||
.
|
||
.It Fl -trace-env
|
||
Print information about any access to environment variables done in the current Node.js
|
||
instance to stderr, including:
|
||
.Bl -bullet
|
||
.It
|
||
The environment variable reads that Node.js does internally.
|
||
.It
|
||
Writes in the form of \fBprocess.env.KEY = "SOME VALUE"\fR.
|
||
.It
|
||
Reads in the form of \fBprocess.env.KEY\fR.
|
||
.It
|
||
Definitions in the form of \fBObject.defineProperty(process.env, 'KEY', {...})\fR.
|
||
.It
|
||
Queries in the form of \fBObject.hasOwn(process.env, 'KEY')\fR,
|
||
\fBprocess.env.hasOwnProperty('KEY')\fR or \fB'KEY' in process.env\fR.
|
||
.It
|
||
Deletions in the form of \fBdelete process.env.KEY\fR.
|
||
.It
|
||
Enumerations inf the form of \fB...process.env\fR or \fBObject.keys(process.env)\fR.
|
||
.El
|
||
Only the names of the environment variables being accessed are printed. The values are not printed.
|
||
To print the stack trace of the access, use \fB--trace-env-js-stack\fR and/or
|
||
\fB--trace-env-native-stack\fR.
|
||
.
|
||
.It Fl -trace-env-js-stack
|
||
In addition to what \fB--trace-env\fR does, this prints the JavaScript stack trace of the access.
|
||
.
|
||
.It Fl -trace-env-native-stack
|
||
In addition to what \fB--trace-env\fR does, this prints the native stack trace of the access.
|
||
.
|
||
.It Fl -trace-event-categories
|
||
A comma separated list of categories that should be traced when trace event
|
||
tracing is enabled using \fB--trace-events-enabled\fR.
|
||
.
|
||
.It Fl -trace-event-file-pattern
|
||
Template string specifying the filepath for the trace event data, it
|
||
supports \fB${rotation}\fR and \fB${pid}\fR.
|
||
.
|
||
.It Fl -trace-events-enabled
|
||
Enables the collection of trace event tracing information.
|
||
.
|
||
.It Fl -trace-exit
|
||
Prints a stack trace whenever an environment is exited proactively,
|
||
i.e. invoking \fBprocess.exit()\fR.
|
||
.
|
||
.It Fl -trace-require-module Ns = Ns Ar mode
|
||
Prints information about usage of Loading ECMAScript modules using \fBrequire()\fR.
|
||
When \fBmode\fR is \fBall\fR, all usage is printed. When \fBmode\fR is \fBno-node-modules\fR, usage
|
||
from the \fBnode_modules\fR folder is excluded.
|
||
.
|
||
.It Fl -trace-sigint
|
||
Prints a stack trace on SIGINT.
|
||
.
|
||
.It Fl -trace-sync-io
|
||
Prints a stack trace whenever synchronous I/O is detected after the first turn
|
||
of the event loop.
|
||
.
|
||
.It Fl -trace-tls
|
||
Prints TLS packet trace information to \fBstderr\fR. This can be used to debug TLS
|
||
connection problems.
|
||
.
|
||
.It Fl -trace-uncaught
|
||
Print stack traces for uncaught exceptions; usually, the stack trace associated
|
||
with the creation of an \fBError\fR is printed, whereas this makes Node.js also
|
||
print the stack trace associated with throwing the value (which does not need
|
||
to be an \fBError\fR instance).
|
||
Enabling this option may affect garbage collection behavior negatively.
|
||
.
|
||
.It Fl -trace-warnings
|
||
Print stack traces for process warnings (including deprecations).
|
||
.
|
||
.It Fl -track-heap-objects
|
||
Track heap object allocations for heap snapshots.
|
||
.
|
||
.It Fl -unhandled-rejections Ns = Ns Ar mode
|
||
Using this flag allows to change what should happen when an unhandled rejection
|
||
occurs. One of the following modes can be chosen:
|
||
.Bl -bullet
|
||
.It
|
||
\fBthrow\fR: Emit \fBunhandledRejection\fR. If this hook is not set, raise the
|
||
unhandled rejection as an uncaught exception. This is the default.
|
||
.It
|
||
\fBstrict\fR: Raise the unhandled rejection as an uncaught exception. If the
|
||
exception is handled, \fBunhandledRejection\fR is emitted.
|
||
.It
|
||
\fBwarn\fR: Always trigger a warning, no matter if the \fBunhandledRejection\fR
|
||
hook is set or not but do not print the deprecation warning.
|
||
.It
|
||
\fBwarn-with-error-code\fR: Emit \fBunhandledRejection\fR. If this hook is not
|
||
set, trigger a warning, and set the process exit code to 1.
|
||
.It
|
||
\fBnone\fR: Silence all warnings.
|
||
.El
|
||
If a rejection happens during the command line entry point's ES module static
|
||
loading phase, it will always raise it as an uncaught exception.
|
||
.
|
||
.It Fl -use-bundled-ca , Fl -use-openssl-ca
|
||
Use bundled Mozilla CA store as supplied by current Node.js version
|
||
or use OpenSSL's default CA store. The default store is selectable
|
||
at build-time.
|
||
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store
|
||
that is fixed at release time. It is identical on all supported platforms.
|
||
Using OpenSSL store allows for external modifications of the store. For most
|
||
Linux and BSD distributions, this store is maintained by the distribution
|
||
maintainers and system administrators. OpenSSL CA store location is dependent on
|
||
configuration of the OpenSSL library but this can be altered at runtime using
|
||
environment variables.
|
||
See \fBSSL_CERT_DIR\fR and \fBSSL_CERT_FILE\fR.
|
||
.
|
||
.It Fl -use-env-proxy
|
||
When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR
|
||
environment variables during startup, and tunnels requests over the
|
||
specified proxy.
|
||
This is equivalent to setting the \fBNODE_USE_ENV_PROXY=1\fR environment variable.
|
||
When both are set, \fB--use-env-proxy\fR takes precedence.
|
||
.
|
||
.It Fl -use-largepages Ns = Ns Ar mode
|
||
Re-map the Node.js static code to large memory pages at startup. If supported on
|
||
the target system, this will cause the Node.js static code to be moved onto 2
|
||
MiB pages instead of 4 KiB pages.
|
||
The following values are valid for \fBmode\fR:
|
||
.Bl -bullet
|
||
.It
|
||
\fBoff\fR: No mapping will be attempted. This is the default.
|
||
.It
|
||
\fBon\fR: If supported by the OS, mapping will be attempted. Failure to map will
|
||
be ignored and a message will be printed to standard error.
|
||
.It
|
||
\fBsilent\fR: If supported by the OS, mapping will be attempted. Failure to map
|
||
will be ignored and will not be reported.
|
||
.El
|
||
.
|
||
.It Fl -use-system-ca
|
||
Node.js uses the trusted CA certificates present in the system store along with
|
||
the \fB--use-bundled-ca\fR option and the \fBNODE_EXTRA_CA_CERTS\fR environment variable.
|
||
On platforms other than Windows and macOS, this loads certificates from the directory
|
||
and file trusted by OpenSSL, similar to \fB--use-openssl-ca\fR, with the difference being
|
||
that it caches the certificates after first load.
|
||
On Windows and macOS, the certificate trust policy is similar to
|
||
Chromium's policy for locally trusted certificates, but with some differences:
|
||
On macOS, the following settings are respected:
|
||
.Bl -bullet
|
||
.It
|
||
Default and System Keychains.Bl -bullet
|
||
.It
|
||
Trust:.Bl -bullet
|
||
.It
|
||
Any certificate where the “When using this certificate” flag is set to “Always Trust” or
|
||
.It
|
||
Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Always Trust”.
|
||
.El
|
||
.It
|
||
The certificate must also be valid, with "X.509 Basic Policy" set to “Always Trust”.
|
||
.El
|
||
.El
|
||
On Windows, the following settings are respected:
|
||
.Bl -bullet
|
||
.It
|
||
Local Machine (accessed via \fBcertlm.msc\fR).Bl -bullet
|
||
.It
|
||
Trust:.Bl -bullet
|
||
.It
|
||
Trusted Root Certification Authorities
|
||
.It
|
||
Trusted People
|
||
.It
|
||
Enterprise Trust -> Enterprise -> Trusted Root Certification Authorities
|
||
.It
|
||
Enterprise Trust -> Enterprise -> Trusted People
|
||
.It
|
||
Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities
|
||
.It
|
||
Enterprise Trust -> Group Policy -> Trusted People
|
||
.El
|
||
.El
|
||
.It
|
||
Current User (accessed via \fBcertmgr.msc\fR).Bl -bullet
|
||
.It
|
||
Trust:.Bl -bullet
|
||
.It
|
||
Trusted Root Certification Authorities
|
||
.It
|
||
Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities
|
||
.El
|
||
.El
|
||
.El
|
||
On Windows and macOS, Node.js would check that the user settings for the trusted
|
||
certificates do not forbid them for TLS server authentication before using them.
|
||
Node.js currently does not support distrust/revocation of certificates
|
||
from another source based on system settings.
|
||
On other systems, Node.js loads certificates from the default certificate file
|
||
(typically \fB/etc/ssl/cert.pem\fR) and default certificate directory (typically
|
||
\fB/etc/ssl/certs\fR) that the version of OpenSSL that Node.js links to respects.
|
||
This typically works with the convention on major Linux distributions and other
|
||
Unix-like systems. If the overriding OpenSSL environment variables
|
||
(typically \fBSSL_CERT_FILE\fR and \fBSSL_CERT_DIR\fR, depending on the configuration
|
||
of the OpenSSL that Node.js links to) are set, the specified paths will be used to load
|
||
certificates instead. These environment variables can be used as workarounds
|
||
if the conventional paths used by the version of OpenSSL Node.js links to are
|
||
not consistent with the system configuration that the users have for some reason.
|
||
.
|
||
.It Fl -v8-options
|
||
Print V8 command-line options.
|
||
.
|
||
.It Fl -v8-pool-size Ns = Ns Ar num
|
||
Set V8's thread pool size which will be used to allocate background jobs.
|
||
If set to \fB0\fR then Node.js will choose an appropriate size of the thread pool
|
||
based on an estimate of the amount of parallelism.
|
||
The amount of parallelism refers to the number of computations that can be
|
||
carried out simultaneously in a given machine. In general, it's the same as the
|
||
amount of CPUs, but it may diverge in environments such as VMs or containers.
|
||
.
|
||
.It Fl v , Fl -version
|
||
Print node's version.
|
||
.
|
||
.It Fl -watch
|
||
Starts Node.js in watch mode.
|
||
When in watch mode, changes in the watched files cause the Node.js process to
|
||
restart.
|
||
By default, watch mode will watch the entry point
|
||
and any required or imported module.
|
||
Use \fB--watch-path\fR to specify what paths to watch.
|
||
This flag cannot be combined with
|
||
\fB--check\fR, \fB--eval\fR, \fB--interactive\fR, or the REPL.
|
||
Note: The \fB--watch\fR flag requires a file path as an argument and is incompatible
|
||
with \fB--run\fR or inline script input, as \fB--run\fR takes precedence and ignores watch
|
||
mode. If no file is provided, Node.js will exit with status code \fB9\fR.
|
||
.Bd -literal
|
||
node --watch index.js
|
||
.Ed
|
||
.
|
||
.It Fl -watch-kill-signal
|
||
Customizes the signal sent to the process on watch mode restarts.
|
||
.Bd -literal
|
||
node --watch --watch-kill-signal SIGINT test.js
|
||
.Ed
|
||
.
|
||
.It Fl -watch-path
|
||
Starts Node.js in watch mode and specifies what paths to watch.
|
||
When in watch mode, changes in the watched paths cause the Node.js process to
|
||
restart.
|
||
This will turn off watching of required or imported modules, even when used in
|
||
combination with \fB--watch\fR.
|
||
This flag cannot be combined with
|
||
\fB--check\fR, \fB--eval\fR, \fB--interactive\fR, \fB--test\fR, or the REPL.
|
||
Note: Using \fB--watch-path\fR implicitly enables \fB--watch\fR, which requires a file path
|
||
and is incompatible with \fB--run\fR, as \fB--run\fR takes precedence and ignores watch mode.
|
||
.Bd -literal
|
||
node --watch-path=./src --watch-path=./tests index.js
|
||
.Ed
|
||
This option is only supported on macOS and Windows.
|
||
An \fBERR_FEATURE_UNAVAILABLE_ON_PLATFORM\fR exception will be thrown
|
||
when the option is used on a platform that does not support it.
|
||
.
|
||
.It Fl -watch-preserve-output
|
||
Disable the clearing of the console when watch mode restarts the process.
|
||
.Bd -literal
|
||
node --watch --watch-preserve-output test.js
|
||
.Ed
|
||
.
|
||
.It Fl -zero-fill-buffers
|
||
Automatically zero-fills all newly allocated \fBBuffer\fR instances.
|
||
.
|
||
|
||
.El
|
||
.
|
||
.Sh ENVIRONMENT
|
||
.Bl -tag -width 6n
|
||
.It Ev FORCE_COLOR Ar [1, 2, 3]
|
||
The \fBFORCE_COLOR\fR environment variable is used to
|
||
enable ANSI colorized output. The value may be:
|
||
.Bl -bullet
|
||
.It
|
||
\fB1\fR, \fBtrue\fR, or the empty string \fB''\fR indicate 16-color support,
|
||
.It
|
||
\fB2\fR to indicate 256-color support, or
|
||
.It
|
||
\fB3\fR to indicate 16 million-color support.
|
||
.El
|
||
When \fBFORCE_COLOR\fR is used and set to a supported value, both the \fBNO_COLOR\fR,
|
||
and \fBNODE_DISABLE_COLORS\fR environment variables are ignored.
|
||
Any other value will result in colorized output being disabled.
|
||
.
|
||
.It Ev NODE_COMPILE_CACHE Ar dir
|
||
Enable the module compile cache for the Node.js instance. See the documentation of
|
||
module compile cache for details.
|
||
.
|
||
.It Ev NODE_COMPILE_CACHE_PORTABLE Ar 1
|
||
When set to 1, the module compile cache can be reused across different directory
|
||
locations as long as the module layout relative to the cache directory remains the same.
|
||
.
|
||
.It Ev NODE_DEBUG Ar module[,…]
|
||
\fB','\fR-separated list of core modules that should print debug information.
|
||
.
|
||
.It Ev NODE_DEBUG_NATIVE Ar module[,…]
|
||
\fB','\fR-separated list of core C++ modules that should print debug information.
|
||
.
|
||
.It Ev NODE_DISABLE_COLORS Ar 1
|
||
When set, colors will not be used in the REPL.
|
||
.
|
||
.It Ev NODE_DISABLE_COMPILE_CACHE Ar 1
|
||
|
||
Disable the module compile cache for the Node.js instance. See the documentation of
|
||
module compile cache for details.
|
||
.
|
||
.It Ev NODE_EXTRA_CA_CERTS Ar file
|
||
When set, the well known "root" CAs (like VeriSign) will be extended with the
|
||
extra certificates in \fBfile\fR. The file should consist of one or more trusted
|
||
certificates in PEM format. A message will be emitted (once) with
|
||
\fBprocess.emitWarning()\fR if the file is missing or
|
||
malformed, but any errors are otherwise ignored.
|
||
Neither the well known nor extra certificates are used when the \fBca\fR
|
||
options property is explicitly specified for a TLS or HTTPS client or server.
|
||
This environment variable is ignored when \fBnode\fR runs as setuid root or
|
||
has Linux file capabilities set.
|
||
The \fBNODE_EXTRA_CA_CERTS\fR environment variable is only read when the Node.js
|
||
process is first launched. Changing the value at runtime using
|
||
\fBprocess.env.NODE_EXTRA_CA_CERTS\fR has no effect on the current process.
|
||
.
|
||
.It Ev NODE_ICU_DATA Ar file
|
||
Data path for ICU (\fBIntl\fR object) data. Will extend linked-in data when compiled
|
||
with small-icu support.
|
||
.
|
||
.It Ev NODE_NO_WARNINGS Ar 1
|
||
When set to \fB1\fR, process warnings are silenced.
|
||
.
|
||
.It Ev NODE_OPTIONS Ar options...
|
||
A space-separated list of command-line options. \fBoptions...\fR are interpreted
|
||
before command-line options, so command-line options will override or
|
||
compound after anything in \fBoptions...\fR. Node.js will exit with an error if
|
||
an option that is not allowed in the environment is used, such as \fB-p\fR or a
|
||
script file.
|
||
If an option value contains a space, it can be escaped using double quotes:
|
||
.Bd -literal
|
||
NODE_OPTIONS='--require "./my path/file.js"'
|
||
.Ed
|
||
A singleton flag passed as a command-line option will override the same flag
|
||
passed into \fBNODE_OPTIONS\fR:
|
||
.Bd -literal
|
||
# The inspector will be available on port 5555
|
||
NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555
|
||
.Ed
|
||
A flag that can be passed multiple times will be treated as if its
|
||
\fBNODE_OPTIONS\fR instances were passed first, and then its command-line
|
||
instances afterwards:
|
||
.Bd -literal
|
||
NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
|
||
# is equivalent to:
|
||
node --require "./a.js" --require "./b.js"
|
||
.Ed
|
||
Node.js options that are allowed are in the following list. If an option
|
||
supports both --XX and --no-XX variants, they are both supported but only
|
||
one is included in the list below.
|
||
.Bl -bullet
|
||
.It
|
||
\fB--allow-addons\fR
|
||
.It
|
||
\fB--allow-child-process\fR
|
||
.It
|
||
\fB--allow-fs-read\fR
|
||
.It
|
||
\fB--allow-fs-write\fR
|
||
.It
|
||
\fB--allow-inspector\fR
|
||
.It
|
||
\fB--allow-net\fR
|
||
.It
|
||
\fB--allow-wasi\fR
|
||
.It
|
||
\fB--allow-worker\fR
|
||
.It
|
||
\fB--conditions\fR, \fB-C\fR
|
||
.It
|
||
\fB--cpu-prof-dir\fR
|
||
.It
|
||
\fB--cpu-prof-interval\fR
|
||
.It
|
||
\fB--cpu-prof-name\fR
|
||
.It
|
||
\fB--cpu-prof\fR
|
||
.It
|
||
\fB--diagnostic-dir\fR
|
||
.It
|
||
\fB--disable-proto\fR
|
||
.It
|
||
\fB--disable-sigusr1\fR
|
||
.It
|
||
\fB--disable-warning\fR
|
||
.It
|
||
\fB--disable-wasm-trap-handler\fR
|
||
.It
|
||
\fB--dns-result-order\fR
|
||
.It
|
||
\fB--enable-fips\fR
|
||
.It
|
||
\fB--enable-network-family-autoselection\fR
|
||
.It
|
||
\fB--enable-source-maps\fR
|
||
.It
|
||
\fB--entry-url\fR
|
||
.It
|
||
\fB--experimental-abortcontroller\fR
|
||
.It
|
||
\fB--experimental-addon-modules\fR
|
||
.It
|
||
\fB--experimental-detect-module\fR
|
||
.It
|
||
\fB--experimental-eventsource\fR
|
||
.It
|
||
\fB--experimental-import-meta-resolve\fR
|
||
.It
|
||
\fB--experimental-json-modules\fR
|
||
.It
|
||
\fB--experimental-loader\fR
|
||
.It
|
||
\fB--experimental-modules\fR
|
||
.It
|
||
\fB--experimental-print-required-tla\fR
|
||
.It
|
||
\fB--experimental-quic\fR
|
||
.It
|
||
\fB--experimental-require-module\fR
|
||
.It
|
||
\fB--experimental-shadow-realm\fR
|
||
.It
|
||
\fB--experimental-specifier-resolution\fR
|
||
.It
|
||
\fB--experimental-test-isolation\fR
|
||
.It
|
||
\fB--experimental-top-level-await\fR
|
||
.It
|
||
\fB--experimental-vm-modules\fR
|
||
.It
|
||
\fB--experimental-wasi-unstable-preview1\fR
|
||
.It
|
||
\fB--force-context-aware\fR
|
||
.It
|
||
\fB--force-fips\fR
|
||
.It
|
||
\fB--force-node-api-uncaught-exceptions-policy\fR
|
||
.It
|
||
\fB--frozen-intrinsics\fR
|
||
.It
|
||
\fB--heap-prof-dir\fR
|
||
.It
|
||
\fB--heap-prof-interval\fR
|
||
.It
|
||
\fB--heap-prof-name\fR
|
||
.It
|
||
\fB--heap-prof\fR
|
||
.It
|
||
\fB--heapsnapshot-near-heap-limit\fR
|
||
.It
|
||
\fB--heapsnapshot-signal\fR
|
||
.It
|
||
\fB--http-parser\fR
|
||
.It
|
||
\fB--icu-data-dir\fR
|
||
.It
|
||
\fB--import\fR
|
||
.It
|
||
\fB--input-type\fR
|
||
.It
|
||
\fB--insecure-http-parser\fR
|
||
.It
|
||
\fB--inspect-brk\fR
|
||
.It
|
||
\fB--inspect-port\fR, \fB--debug-port\fR
|
||
.It
|
||
\fB--inspect-publish-uid\fR
|
||
.It
|
||
\fB--inspect-wait\fR
|
||
.It
|
||
\fB--inspect\fR
|
||
.It
|
||
\fB--localstorage-file\fR
|
||
.It
|
||
\fB--max-http-header-size\fR
|
||
.It
|
||
\fB--max-old-space-size-percentage\fR
|
||
.It
|
||
\fB--napi-modules\fR
|
||
.It
|
||
\fB--network-family-autoselection-attempt-timeout\fR
|
||
.It
|
||
\fB--no-addons\fR
|
||
.It
|
||
\fB--no-async-context-frame\fR
|
||
.It
|
||
\fB--no-deprecation\fR
|
||
.It
|
||
\fB--no-experimental-global-navigator\fR
|
||
.It
|
||
\fB--no-experimental-repl-await\fR
|
||
.It
|
||
\fB--no-experimental-sqlite\fR
|
||
.It
|
||
\fB--no-experimental-strip-types\fR
|
||
.It
|
||
\fB--no-experimental-websocket\fR
|
||
.It
|
||
\fB--no-experimental-webstorage\fR
|
||
.It
|
||
\fB--no-extra-info-on-fatal-exception\fR
|
||
.It
|
||
\fB--no-force-async-hooks-checks\fR
|
||
.It
|
||
\fB--no-global-search-paths\fR
|
||
.It
|
||
\fB--no-network-family-autoselection\fR
|
||
.It
|
||
\fB--no-strip-types\fR
|
||
.It
|
||
\fB--no-warnings\fR
|
||
.It
|
||
\fB--no-webstorage\fR
|
||
.It
|
||
\fB--node-memory-debug\fR
|
||
.It
|
||
\fB--openssl-config\fR
|
||
.It
|
||
\fB--openssl-legacy-provider\fR
|
||
.It
|
||
\fB--openssl-shared-config\fR
|
||
.It
|
||
\fB--pending-deprecation\fR
|
||
.It
|
||
\fB--permission\fR
|
||
.It
|
||
\fB--permission-audit\fR
|
||
.It
|
||
\fB--preserve-symlinks-main\fR
|
||
.It
|
||
\fB--preserve-symlinks\fR
|
||
.It
|
||
\fB--prof-process\fR
|
||
.It
|
||
\fB--redirect-warnings\fR
|
||
.It
|
||
\fB--report-compact\fR
|
||
.It
|
||
\fB--report-dir\fR, \fB--report-directory\fR
|
||
.It
|
||
\fB--report-exclude-env\fR
|
||
.It
|
||
\fB--report-exclude-network\fR
|
||
.It
|
||
\fB--report-filename\fR
|
||
.It
|
||
\fB--report-on-fatalerror\fR
|
||
.It
|
||
\fB--report-on-signal\fR
|
||
.It
|
||
\fB--report-signal\fR
|
||
.It
|
||
\fB--report-uncaught-exception\fR
|
||
.It
|
||
\fB--require-module\fR
|
||
.It
|
||
\fB--require\fR, \fB-r\fR
|
||
.It
|
||
\fB--secure-heap-min\fR
|
||
.It
|
||
\fB--secure-heap\fR
|
||
.It
|
||
\fB--snapshot-blob\fR
|
||
.It
|
||
\fB--test-coverage-branches\fR
|
||
.It
|
||
\fB--test-coverage-exclude\fR
|
||
.It
|
||
\fB--test-coverage-functions\fR
|
||
.It
|
||
\fB--test-coverage-include\fR
|
||
.It
|
||
\fB--test-coverage-lines\fR
|
||
.It
|
||
\fB--test-global-setup\fR
|
||
.It
|
||
\fB--test-isolation\fR
|
||
.It
|
||
\fB--test-name-pattern\fR
|
||
.It
|
||
\fB--test-only\fR
|
||
.It
|
||
\fB--test-reporter-destination\fR
|
||
.It
|
||
\fB--test-randomize\fR
|
||
.It
|
||
\fB--test-random-seed\fR
|
||
.It
|
||
\fB--test-reporter\fR
|
||
.It
|
||
\fB--test-rerun-failures\fR
|
||
.It
|
||
\fB--test-shard\fR
|
||
.It
|
||
\fB--test-skip-pattern\fR
|
||
.It
|
||
\fB--throw-deprecation\fR
|
||
.It
|
||
\fB--title\fR
|
||
.It
|
||
\fB--tls-cipher-list\fR
|
||
.It
|
||
\fB--tls-keylog\fR
|
||
.It
|
||
\fB--tls-max-v1.2\fR
|
||
.It
|
||
\fB--tls-max-v1.3\fR
|
||
.It
|
||
\fB--tls-min-v1.0\fR
|
||
.It
|
||
\fB--tls-min-v1.1\fR
|
||
.It
|
||
\fB--tls-min-v1.2\fR
|
||
.It
|
||
\fB--tls-min-v1.3\fR
|
||
.It
|
||
\fB--trace-deprecation\fR
|
||
.It
|
||
\fB--trace-env-js-stack\fR
|
||
.It
|
||
\fB--trace-env-native-stack\fR
|
||
.It
|
||
\fB--trace-env\fR
|
||
.It
|
||
\fB--trace-event-categories\fR
|
||
.It
|
||
\fB--trace-event-file-pattern\fR
|
||
.It
|
||
\fB--trace-events-enabled\fR
|
||
.It
|
||
\fB--trace-exit\fR
|
||
.It
|
||
\fB--trace-require-module\fR
|
||
.It
|
||
\fB--trace-sigint\fR
|
||
.It
|
||
\fB--trace-sync-io\fR
|
||
.It
|
||
\fB--trace-tls\fR
|
||
.It
|
||
\fB--trace-uncaught\fR
|
||
.It
|
||
\fB--trace-warnings\fR
|
||
.It
|
||
\fB--track-heap-objects\fR
|
||
.It
|
||
\fB--unhandled-rejections\fR
|
||
.It
|
||
\fB--use-bundled-ca\fR
|
||
.It
|
||
\fB--use-env-proxy\fR
|
||
.It
|
||
\fB--use-largepages\fR
|
||
.It
|
||
\fB--use-openssl-ca\fR
|
||
.It
|
||
\fB--use-system-ca\fR
|
||
.It
|
||
\fB--v8-pool-size\fR
|
||
.It
|
||
\fB--watch-kill-signal\fR
|
||
.It
|
||
\fB--watch-path\fR
|
||
.It
|
||
\fB--watch-preserve-output\fR
|
||
.It
|
||
\fB--watch\fR
|
||
.It
|
||
\fB--zero-fill-buffers\fR
|
||
.El
|
||
V8 options that are allowed are:
|
||
.Bl -bullet
|
||
.It
|
||
\fB--abort-on-uncaught-exception\fR
|
||
.It
|
||
\fB--disallow-code-generation-from-strings\fR
|
||
.It
|
||
\fB--enable-etw-stack-walking\fR
|
||
.It
|
||
\fB--expose-gc\fR
|
||
.It
|
||
\fB--interpreted-frames-native-stack\fR
|
||
.It
|
||
\fB--jitless\fR
|
||
.It
|
||
\fB--max-old-space-size\fR
|
||
.It
|
||
\fB--max-semi-space-size\fR
|
||
.It
|
||
\fB--perf-basic-prof-only-functions\fR
|
||
.It
|
||
\fB--perf-basic-prof\fR
|
||
.It
|
||
\fB--perf-prof-unwinding-info\fR
|
||
.It
|
||
\fB--perf-prof\fR
|
||
.It
|
||
\fB--stack-trace-limit\fR
|
||
.El
|
||
\fB--perf-basic-prof-only-functions\fR, \fB--perf-basic-prof\fR,
|
||
\fB--perf-prof-unwinding-info\fR, and \fB--perf-prof\fR are only available on Linux.
|
||
\fB--enable-etw-stack-walking\fR is only available on Windows.
|
||
.
|
||
.It Ev NODE_PATH Ar path[:…]
|
||
\fB':'\fR-separated list of directories prefixed to the module search path.
|
||
On Windows, this is a \fB';'\fR-separated list instead.
|
||
.
|
||
.It Ev NODE_PENDING_DEPRECATION Ar 1
|
||
When set to \fB1\fR, emit pending deprecation warnings.
|
||
Pending deprecations are generally identical to a runtime deprecation with the
|
||
notable exception that they are turned \fIoff\fR by default and will not be emitted
|
||
unless either the \fB--pending-deprecation\fR command-line flag, or the
|
||
\fBNODE_PENDING_DEPRECATION=1\fR environment variable, is set. Pending deprecations
|
||
are used to provide a kind of selective "early warning" mechanism that
|
||
developers may leverage to detect deprecated API usage.
|
||
.
|
||
.It Ev NODE_PENDING_PIPE_INSTANCES Ar instances
|
||
Set the number of pending pipe instance handles when the pipe server is waiting
|
||
for connections. This setting applies to Windows only.
|
||
.
|
||
.It Ev NODE_PRESERVE_SYMLINKS Ar 1
|
||
When set to \fB1\fR, instructs the module loader to preserve symbolic links when
|
||
resolving and caching modules.
|
||
.
|
||
.It Ev NODE_REDIRECT_WARNINGS Ar file
|
||
When set, process warnings will be emitted to the given file instead of
|
||
printing to stderr. The file will be created if it does not exist, and will be
|
||
appended to if it does. If an error occurs while attempting to write the
|
||
warning to the file, the warning will be written to stderr instead. This is
|
||
equivalent to using the \fB--redirect-warnings=file\fR command-line flag.
|
||
.
|
||
.It Ev NODE_REPL_EXTERNAL_MODULE Ar file
|
||
Path to a Node.js module which will be loaded in place of the built-in REPL.
|
||
Overriding this value to an empty string (\fB''\fR) will use the built-in REPL.
|
||
.
|
||
.It Ev NODE_REPL_HISTORY Ar file
|
||
Path to the file used to store the persistent REPL history. The default path is
|
||
\fB~/.node_repl_history\fR, which is overridden by this variable. Setting the value
|
||
to an empty string (\fB''\fR or \fB' '\fR) disables persistent REPL history.
|
||
.
|
||
.It Ev NODE_SKIP_PLATFORM_CHECK Ar value
|
||
If \fBvalue\fR equals \fB'1'\fR, the check for a supported platform is skipped during
|
||
Node.js startup. Node.js might not execute correctly. Any issues encountered
|
||
on unsupported platforms will not be fixed.
|
||
.
|
||
.It Ev NODE_TEST_CONTEXT Ar value
|
||
If \fBvalue\fR equals \fB'child'\fR, test reporter options will be overridden and test
|
||
output will be sent to stdout in the TAP format. If any other value is provided,
|
||
Node.js makes no guarantees about the reporter format used or its stability.
|
||
.
|
||
.It Ev NODE_TLS_REJECT_UNAUTHORIZED Ar value
|
||
If \fBvalue\fR equals \fB'0'\fR, certificate validation is disabled for TLS connections.
|
||
This makes TLS, and HTTPS by extension, insecure. The use of this environment
|
||
variable is strongly discouraged.
|
||
.
|
||
.It Ev NODE_USE_ENV_PROXY Ar 1
|
||
|
||
When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR
|
||
environment variables during startup, and tunnels requests over the
|
||
specified proxy.
|
||
This can also be enabled using the \fB--use-env-proxy\fR command-line flag.
|
||
When both are set, \fB--use-env-proxy\fR takes precedence.
|
||
.
|
||
.It Ev NODE_USE_SYSTEM_CA Ar 1
|
||
Node.js uses the trusted CA certificates present in the system store along with
|
||
the \fB--use-bundled-ca\fR option and the \fBNODE_EXTRA_CA_CERTS\fR environment variable.
|
||
This can also be enabled using the \fB--use-system-ca\fR command-line flag.
|
||
When both are set, \fB--use-system-ca\fR takes precedence.
|
||
.
|
||
.It Ev NODE_V8_COVERAGE Ar dir
|
||
When set, Node.js will begin outputting V8 JavaScript code coverage and
|
||
Source Map data to the directory provided as an argument (coverage
|
||
information is written as JSON to files with a \fBcoverage\fR prefix).
|
||
\fBNODE_V8_COVERAGE\fR will automatically propagate to subprocesses, making it
|
||
easier to instrument applications that call the \fBchild_process.spawn()\fR family
|
||
of functions. \fBNODE_V8_COVERAGE\fR can be set to an empty string, to prevent
|
||
propagation.
|
||
.
|
||
.It Ev NO_COLOR Ar <any>
|
||
\fBNO_COLOR\fR is an alias for \fBNODE_DISABLE_COLORS\fR. The value of the
|
||
environment variable is arbitrary.
|
||
.
|
||
.It Ev OPENSSL_CONF Ar file
|
||
Load an OpenSSL configuration file on startup. Among other uses, this can be
|
||
used to enable FIPS-compliant crypto if Node.js is built with
|
||
\fB./configure --openssl-fips\fR.
|
||
If the \fB--openssl-config\fR command-line option is used, the environment
|
||
variable is ignored.
|
||
.
|
||
.It Ev SSL_CERT_DIR Ar dir
|
||
If \fB--use-openssl-ca\fR is enabled, or if \fB--use-system-ca\fR is enabled on
|
||
platforms other than macOS and Windows, this overrides and sets OpenSSL's directory
|
||
containing trusted certificates.
|
||
Be aware that unless the child environment is explicitly set, this environment
|
||
variable will be inherited by any child processes, and if they use OpenSSL, it
|
||
may cause them to trust the same CAs as node.
|
||
.
|
||
.It Ev SSL_CERT_FILE Ar file
|
||
If \fB--use-openssl-ca\fR is enabled, or if \fB--use-system-ca\fR is enabled on
|
||
platforms other than macOS and Windows, this overrides and sets OpenSSL's file
|
||
containing trusted certificates.
|
||
Be aware that unless the child environment is explicitly set, this environment
|
||
variable will be inherited by any child processes, and if they use OpenSSL, it
|
||
may cause them to trust the same CAs as node.
|
||
.
|
||
.It Ev TZ
|
||
The \fBTZ\fR environment variable is used to specify the timezone configuration.
|
||
While Node.js does not support all of the various ways that \fBTZ\fR is handled in
|
||
other environments, it does support basic timezone IDs (such as
|
||
\fB'Etc/UTC'\fR, \fB'Europe/Paris'\fR, or \fB'America/New_York'\fR).
|
||
It may support a few other abbreviations or aliases, but these are strongly
|
||
discouraged and not guaranteed.
|
||
.Bd -literal
|
||
$ TZ=Europe/Dublin node -pe "new Date().toString()"
|
||
Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)
|
||
.Ed
|
||
.
|
||
.It Ev UV_THREADPOOL_SIZE Ar size
|
||
Set the number of threads used in libuv's threadpool to \fBsize\fR threads.
|
||
Asynchronous system APIs are used by Node.js whenever possible, but where they
|
||
do not exist, libuv's threadpool is used to create asynchronous node APIs based
|
||
on synchronous system APIs. Node.js APIs that use the threadpool are:
|
||
.Bl -bullet
|
||
.It
|
||
all \fBfs\fR APIs, other than the file watcher APIs and those that are explicitly
|
||
synchronous
|
||
.It
|
||
asynchronous crypto APIs such as \fBcrypto.pbkdf2()\fR, \fBcrypto.scrypt()\fR,
|
||
\fBcrypto.randomBytes()\fR, \fBcrypto.randomFill()\fR, \fBcrypto.generateKeyPair()\fR
|
||
.It
|
||
\fBdns.lookup()\fR
|
||
.It
|
||
all \fBzlib\fR APIs, other than those that are explicitly synchronous
|
||
.El
|
||
Because libuv's threadpool has a fixed size, it means that if for whatever
|
||
reason any of these APIs takes a long time, other (seemingly unrelated) APIs
|
||
that run in libuv's threadpool will experience degraded performance. In order to
|
||
mitigate this issue, one potential solution is to increase the size of libuv's
|
||
threadpool by setting the \fB'UV_THREADPOOL_SIZE'\fR environment variable to a value
|
||
greater than \fB4\fR (its current default value). However, setting this from inside
|
||
the process using \fBprocess.env.UV_THREADPOOL_SIZE=size\fR is not guaranteed to work
|
||
as the threadpool would have been created as part of the runtime initialisation
|
||
much before user code is run. For more information, see the libuv threadpool documentation.
|
||
.
|
||
|
||
.El
|
||
.
|
||
.Sh BUGS
|
||
Bugs are tracked in GitHub Issues:
|
||
.Sy https://github.com/nodejs/node/issues
|
||
.
|
||
.Sh COPYRIGHT
|
||
Copyright Node.js contributors.
|
||
Node.js is available under the MIT license.
|
||
.
|
||
.Pp
|
||
Node.js also includes external libraries that are available under a variety of licenses.
|
||
See
|
||
.Sy https://github.com/nodejs/node/blob/HEAD/LICENSE
|
||
for the full license text.
|
||
.
|
||
.Sh SEE ALSO
|
||
Website:
|
||
.Sy https://nodejs.org/
|
||
.
|
||
.Pp
|
||
Documentation:
|
||
.Sy https://nodejs.org/api/
|
||
.
|
||
.Pp
|
||
GitHub repository and issue tracker:
|
||
.Sy https://github.com/nodejs/node
|