.\"

.\" 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