.\"

.\" This file was generated automatically by the @node-core/doc-kit tool.

.\" Please do not edit this file manually. Make any updates to cli.md

.\" and regenerate the file afterward.

.\"

.\" To regenerate this file, run `make doc/node.1`.

.\"

.\"======================================================================

.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-ffi

When using the Permission Model, the process will not be able to use FFI

APIs by default. Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR

exception unless the user explicitly passes the \fB--allow-ffi\fR flag when

starting Node.js. The \fBnode:ffi\fR module also requires the

\fB--experimental-ffi\fR flag and is only available in builds with FFI support.

Example:

.Bd -literal

const { DynamicLibrary, suffix } = require('node:ffi');

const lib = new DynamicLibrary(`./mylib.${suffix}`);

.Ed

.Bd -literal

$ node --permission --experimental-ffi index.js

Error: Access to this API has been restricted. Use --allow-ffi to manage permissions.

at node:internal/main/run_main_module:17:47 {

code: 'ERR_ACCESS_DENIED',

permission: 'FFI'

}

.Ed

.

.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=/folder2/\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.permission.has('fs.read', 'index.js'); // true

process.permission.has('fs.read', 'custom-require.js'); // true

process.permission.has('fs.read', 'custom-require-2.js'); // true

.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=/folder2/\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-openssl-store

When using the Permission Model, the process will not be able to use

OpenSSL STORE loaders by default, for example to load a private key from a

\fB<URL>\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw

an \fBERR_ACCESS_DENIED\fR unless the user explicitly passes the

\fB--allow-openssl-store\fR flag. This permission can be dropped at runtime via

\fBpermission.drop()\fR.

This flag grants broad authority to configured OpenSSL STORE loaders. A loader

may access files, devices, tokens, or the network. Access performed by a loader

is not constrained by the \fBfs.read\fR, \fBfs.write\fR, or \fBnet\fR permission scopes.

.

.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 loading a single entrypoint during the

snapshot building process, which can load built-in modules, but not additional user-land modules.

Users can bundle their applications into a single script with their bundler

of choice before building a snapshot.

As it's complicated to ensure the serializablility of all built-in modules,

which are also growing over time, only a subset of the built-in modules are

well tested to be serializable during the snapshot building process.

The Node.js core test suite checks that a few fairly complex applications

can be snapshotted. The list of built-in modules being

captured by the built-in snapshot of Node.js is considered supported.

When the snapshot builder encounters a built-in module that cannot be

serialized, it may crash the snapshot building process. In that case a typical

workaround would be to delay loading that module until

runtime, using either \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

Node.js enables V8's trap-handler-based WebAssembly bound checks on 64-bit platforms,

which significantly improves WebAssembly performance by eliminating the need for

inline bound checks. This optimization requires allocating a large virtual memory

cage per WebAssembly memory instance (currently typically 8GB for 32-bit WebAssembly memory,

16GB for 64-bit WebAssembly memory) to trap out-of-bound accesses. On most 64-bit

platforms, the virtual memory address space is usually large enough (around 128TB)

to accommodate typical WebAssembly usages, but if the machine has manual limits

on virtual memory (e.g. through \fBulimit -v\fR), WebAssembly memory allocation is

more likely to fail with \fBWebAssembly.Memory(): could not allocate memory\fR.

At startup, Node.js automatically checks whether there is enough virtual memory

available to allocate at least one cage, and if not, the trap-handler optimization

is automatically disabled so that WebAssembly can still run using inline

bound checks (with less optimal performance). But if the application needs to create

many WebAssembly memory instances and the machine still configures a relatively high

limit on virtual memory, allocation of WebAssembly memory instances may still fail

more quickly than expected due to the raised virtual memory usage.

\fB--disable-wasm-trap-handler\fR fully disables this optimization so that WebAssembly memory

instances always use inline bound checks instead of reserving large virtual memory cages.

This allows more instances to be created when the virtual memory address space available

to the Node.js process is limited.

.

.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 mode at startup. With OpenSSL 3, a configured provider named

\fBfips\fR must be available and initialize successfully. With OpenSSL 1.1.1,

Node.js must be built against a FIPS-capable 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.

If \fBscript\fR starts with \fB-\fR, pass it using \fB=\fR (for example,

\fBnode --print --eval=-42\fR) so it is parsed as the value of \fB--eval\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 path , Fl -experimental-config-file

If present, Node.js will look for a configuration file at the specified path.

If the path is not specified, Node.js will look for a \fBnode.config.json\fR file

in the current working directory.

To specify a custom path, use the \fB--experimental-config-file=path\fR form.

The space-separated \fB--experimental-config-file path\fR form is not supported.

The alias \fB--experimental-default-config-file\fR is equivalent to

\fB--experimental-config-file\fR without an argument.

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 or

\fBlatest-vX.x\fR for the latest version of that major release line.

.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

The configuration file can target a specific Node.js major version with

\fBnodeVersion\fR:

.Bd -literal

{

"nodeVersion": 25,

"nodeOptions": {

"watch-path": "src"

}

}

.Ed

To keep multiple version-specific configurations in the same file, use the

\fBconfigs\fR array. Node.js will use the first entry whose \fBnodeVersion\fR matches

the current Node.js major version:

.Bd -literal

{

"$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",

"configs": [

{

"nodeVersion": 25,

"config": {

"$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",

"nodeOptions": {

"watch-path": "src"

}

}

}

]

}

.Ed

When \fBconfigs\fR is used, the top level may only contain \fB$schema\fR and

\fBconfigs\fR. Each \fBconfigs\fR item must define an integer \fBnodeVersion\fR and an

object \fBconfig\fR. A single top-level config does not require \fBnodeVersion\fR, but

if present it must match the current Node.js major version.

When a namespace is present in the

configuration file, Node.js automatically enables the corresponding flag

(e.g., \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

Dotenv NODE_OPTIONS

.It

Configuration file

.El

Values in the configuration file will not override the values in the environment

variables, command-line options, or 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

This flag is an alias for \fB--experimental-config-file\fR without an argument.

If present, Node.js will look for a

\fBnode.config.json\fR file in the current working directory and load it as a

configuration file.

.

.It Fl -experimental-dtls

Enable experimental support for the DTLS protocol. See the

dtls documentation for details.

.

.It Fl -experimental-eventsource

Enable exposition of EventSource Web API on the global scope.

.

.It Fl -experimental-ffi

Enable the experimental \fBnode:ffi\fR module.

This flag is only available in builds with FFI support.

.

.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-import-text

Enable experimental support for importing modules with

\fBwith { type: 'text' }\fR.

.

.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-package-map Ns = Ns Ar <path>

Enable experimental package map resolution. The \fBpath\fR argument specifies the

location of a JSON configuration file that defines package resolution mappings.

.Bd -literal

node --experimental-package-map=./package-map.json app.js

.Ed

When enabled, bare specifier resolution consults the package map for resolution.

This allows explicit control over which packages can import which dependencies.

See Package maps for details on the configuration file format and

resolution algorithm.

.

.It Fl -experimental-print-required-tla

If the ES module graph cannot be \fBrequire()\fR'd because it contains any top-level \fBawait\fR,

this flag allows Node.js to locate and print their locations.

.

.It Fl -experimental-quic

Enable experimental support for the QUIC protocol.

.

.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-stream-iter

Enable the experimental \fBnode:stream/iter\fR module.

.

.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-test-tag-filter Ns = Ns Ar <tag>

Run only tests whose tag set contains \fB<tag>\fR. Tests declare tags via the

\fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or \fBdescribe()\fR; tags

inherit from suites to nested tests by union. Filtering is

case-insensitive.

The flag may be specified more than once; tests must contain \fBevery\fR

filter value to run. See Test tags for details on declaring and

inheriting tags.

.

.It Fl -experimental-vfs

Enable the experimental \fBnode:vfs\fR module.

.

.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 -force-context-aware

Disable loading native addons that are not context-aware.

.

.It Fl -force-fips

Enable FIPS mode at startup and prevent it from being disabled from script

code. The same OpenSSL requirements as \fB--enable-fips\fR apply.

.

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