From b3c0399ece8230d8ae66ea340c41cf0b655a795f Mon Sep 17 00:00:00 2001 From: RedYetiDev <38299977+RedYetiDev@users.noreply.github.com> Date: Mon, 21 Oct 2024 16:53:55 -0400 Subject: [PATCH 1/3] cli: generate man-page --- Makefile | 3 + doc/node.1 | 2289 +++++++++++++++---- test/parallel/test-cli-node-options-docs.js | 24 - tools/lint-md/lint-md.mjs | 31 +- tools/lint-md/man-page.mjs | 8 + tools/lint-md/package-lock.json | 1274 ++++++++++- tools/lint-md/package.json | 1 + 7 files changed, 3096 insertions(+), 534 deletions(-) create mode 100644 tools/lint-md/man-page.mjs diff --git a/Makefile b/Makefile index 36e79eb99de38d..31d61d546cdc9d 100644 --- a/Makefile +++ b/Makefile @@ -807,6 +807,9 @@ doc-only: tools/doc/node_modules \ .PHONY: doc doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary. +doc/node.1: doc/api/cli.md + $(NODE) tools/lint-md/node_modules/@node-core/api-docs-tooling/bin/cli.mjs -t man-page -i doc/api/cli.md -o doc/node.1 + out/doc: mkdir -p $@ cp doc/node-config-schema.json $@ diff --git a/doc/node.1 b/doc/node.1 index 9ed99be3b7771e..89aa1fee9e5c8a 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1,54 +1,33 @@ .\" -.\" This manpage is written in mdoc(7). +.\" This file was generated automatically by the api-docs-tooling tool. +.\" Please do not edit this file manually. Make any updates to cli.md +.\" and regenerate the file afterward. .\" -.\" * 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. +.\" To regenerate this file, run `make doc/node.1`. .\" .\"====================================================================== -. -.tr -\-^\(ha~\(ti`\(ga -.Dd 2018 +.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 Fl e Ar string | Ar script.js | Fl -.Op Fl - +.Op Ar v8 options +.Op Ar | Fl e Ar string | Fl - .Op Ar arguments ... . .Nm node -.Cm inspect -.Op Fl e Ar string | Ar script.js | Fl | Ar : +.Cm inspect, +.Op Ar | Fl e Ar string | Ar : .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. @@ -59,300 +38,896 @@ without arguments to start a REPL. . .Sh OPTIONS .Bl -tag -width 6n -.It Sy - -Alias for stdin, analogous to the use of - in other command-line utilities. -The executed script is read from stdin, and remaining arguments are passed to the script. +.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 command-line options. -Pass the rest of the arguments to the script. -.Pp +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 will be used as a script filename. +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 analysis. -. -.It Fl -allow-fs-read -Allow file system read access when using the permission model. -. -.It Fl -allow-fs-write -Allow file system write access when using the permission model. +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 -Allow using native addons when using the permission model. +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. (/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 -Allow spawning process when using the permission model. +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 +Unlike \fBchild_process.spawn\fR, the \fBchild_process.fork\fR API copies the execution +arguments from the parent process. This means that if you start Node.js with the +Permission Model enabled and include the \fB--allow-child-process\fR flag, calling +\fBchild_process.fork()\fR will propagate all Permission Model flags to the child +process. +. +.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 also needs to be allowed. Consider the following example: +.Bd -literal +$ node --permission index.js + +Error: Access to this API has been restricted + at node:internal/main/run_main_module:23:47 { + code: 'ERR_ACCESS_DENIED', + permission: 'FileSystemRead', + resource: '/Users/rafaelgss/repos/os/node/index.js' +} +.Ed +The process needs to have access to the \fBindex.js\fR module: +.Bd -literal +node --permission --allow-fs-read=/path/to/index.js index.js +.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-wasi -Allow execution of WASI when using the permission model. +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 -Allow creating worker threads when using the permission model. +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-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. +Currently the support for run-time snapshot is experimental in that: +.Bl -bullet +.It +User-land modules are not yet supported in the snapshot, so only +one single file can be snapshotted. Users can bundle their applications +into a single script with their bundler of choice before building +a snapshot, however. +.It +Only a subset of the built-in modules work in the snapshot, though the +Node.js core test suite checks that a few fairly complex applications +can be snapshotted. Support for more modules are being added. If any +crashes or buggy behaviors occur when building a snapshot, please file +a report in the Node.js issue tracker and link to it in the +tracking issue for user-land snapshots. +.El +. +.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\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\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. -. -.It Fl C , Fl -conditions Ar string -Use custom conditional exports conditions. -.Ar string +.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 -Start the V8 CPU profiler on start up, and write the CPU profile to disk -before exit. If -.Fl -cpu-prof-dir -is not specified, the profile will be written to the current working directory -with a generated file name. +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 will be used as-is; patterns such as +\fB${hhmmss}\fR or \fB${pid}\fR are not supported. +.Bd -literal +$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js +$ ls *.cpuprofile +'CPU.${pid}.cpuprofile' +.Ed . .It Fl -cpu-prof-dir -The directory where the CPU profiles generated by -.Fl -cpu-prof -will be placed. +Specify the directory where the CPU profiles generated by \fB--cpu-prof\fR will +be placed. The default value is controlled by the -.Fl -diagnostic-dir . -command-line option. +\fB--diagnostic-dir\fR command-line option. . .It Fl -cpu-prof-interval -The sampling interval in microseconds for the CPU profiles generated by -.Fl -cpu-prof . -The default is -.Sy 1000 . +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 -File name of the V8 CPU profile generated with -.Fl -cpu-prof . +Specify the file name of the CPU profile generated by \fB--cpu-prof\fR. . -.It Fl -diagnostic-dir -Set the directory for all diagnostic output files. -Default is current working directory. -Set the directory to which all diagnostic output files will be written to. +.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: -.Fl -cpu-prof-dir . -.Fl -heap-prof-dir . -.Fl -redirect-warnings . +.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 `Object.prototype.__proto__` property. If -.Ar mode -is `delete`, the property will be removed entirely. If -.Ar mode -is `throw`, accesses to the property will throw an exception with the code -`ERR_PROTO_ACCESS`. -. -.It Fl -disable-wasm-trap-handler Ns = Ns Ar mode -Disable trap-handler-based WebAssembly bound checks and fall back to -inline bound checks so that WebAssembly can be run with limited virtual -memory. +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 +int the code compiled from WebAssembly which may speedup 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 `eval` and `new Function` that generate +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 -`vm` module. +\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 with -.Sy ./configure --openssl-fips . +Enable FIPS-compliant crypto at startup. (Requires Node.js to be built +against FIPS-compatible OpenSSL.) +. +.It Fl -enable-network-family-autoselection +Enables the family autoselection algorithm unless connection options explicitly +disables it. . .It Fl -enable-source-maps -Enable Source Map V3 support for stack traces. +Enable Source Map v3 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 -Interpret the entry point as a 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 config +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 config +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-experimental-strip-types\fR flag is provided. . .It Fl -experimental-addon-modules -Enable experimental addon module support. -. -.It Fl -experimental-config-file -Specifies the configuration file to load. +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 + } +} +.Ed +In the \fBnodeOptions\fR field, only flags that are allowed in \fBNODE_OPTIONS\fR are supported. +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 +.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. +If duplicate keys are present in the configuration file, only +the first key will be used. +The configuration parser will throw an error if the configuration file contains +unknown keys or keys that cannot used in \fBNODE_OPTIONS\fR. +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 -Enable support for automatically loading node.config.json. +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 ES modules support for 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-loader Ns = Ns Ar module -Specify the -.Ar module -to use as a custom module loader. +Specify the \fBmodule\fR containing exported 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 -permission -Enable 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-require-module +Supports loading a synchronous ES module graph in \fBrequire()\fR. +See Loading ECMAScript modules using \fBrequire()\fR. +. +.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-test-coverage -Enable code coverage in the test runner. +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-transform-types -Enable transformation of TypeScript-only syntax into JavaScript code. -. -.It Fl -experimental-eventsource -Enable experimental support for the EventSource Web API. -. -.It Fl -no-experimental-websocket -Disable experimental support for the WebSocket API. -. -.It Fl -experimental-webstorage -Enable experimental support for the Web Storage API. -. -.It Fl -no-experimental-repl-await -Disable top-level await keyword support in REPL. -. -.It Fl -no-experimental-sqlite -Disable the experimental node:sqlite module. -. -.It Fl -no-experimental-strip-types -Disable experimental type-stripping for TypeScript files. +Enables the transformation of TypeScript-only syntax into JavaScript code. +Implies \fB--enable-source-maps\fR. . .It Fl -experimental-vm-modules -Enable experimental ES module support in VM module. +Enable experimental ES Module support in the \fBnode:vm\fR module. . .It Fl -experimental-wasi-unstable-preview1 -Enable experimental WebAssembly System Interface support. This -flag is no longer required as WASI is enabled by default. +Enable experimental WebAssembly System Interface (WASI) support. . .It Fl -experimental-wasm-modules Enable experimental WebAssembly module support. . -.It Fl -experimental-quic -Enable the experimental QUIC support. +.It Fl -experimental-webstorage +Enable experimental \fBWeb Storage\fR support. +. +.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 -.Fl -enable-fips . +Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.) +(Same requirements as \fB--enable-fips\fR.) . -.It Fl -frozen-intrinsics -Enable experimental frozen intrinsics support. +.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 -heapsnapshot-near-heap-limit Ns = Ns Ar max_count -Generate heap snapshot when the V8 heap usage is approaching the heap limit. -No more than the specified number of snapshots will be generated. -. -.It Fl -heapsnapshot-signal Ns = Ns Ar signal -Generate heap snapshot on specified signal. +.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 -Start the V8 heap profiler on start up, and write the heap profile to disk -before exit. If -.Fl -heap-prof-dir -is not specified, the profile will be written to the current working directory -with a generated file name. +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 -The directory where the heap profiles generated by -.Fl -heap-prof -will be placed. +Specify the directory where the heap profiles generated by \fB--heap-prof\fR will +be placed. The default value is controlled by the -.Fl -diagnostic-dir . -command-line option. +\fB--diagnostic-dir\fR command-line option. . .It Fl -heap-prof-interval -The average sampling interval in bytes for the heap profiles generated by -.Fl -heap-prof . -The default is -.Sy 512 * 1024 . +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 -File name of the V8 heap profile generated with -.Fl -heap-prof . +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 -.Ev NODE_ICU_DATA . +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 -Set the module resolution type for input via --eval, --print or STDIN. +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-experimental-strip-types\fR. +The default is \fB"commonjs"\fR. +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 -.Ar host:port -and break at start of user script. +.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 -.Ar host:port -to be used when the inspector is activated. -. -.It Fl -inspect-publish-uid=stderr,http -Specify how the inspector WebSocket URL is exposed. -Valid values are -.Sy stderr -and -.Sy http . -Default is -.Sy stderr,http . -. -.It Fl -inspect-wait Ns = Ns Ar [host:]port -Activate inspector on -.Ar host:port -and wait for debugger to be attached. -. -.It Fl -inspect Ns = Ns Ar [host:]port -Activate inspector on -.Ar host:port . -Default is -.Sy 127.0.0.1:9229 . -.Pp -V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js instances for debugging and profiling. -It uses the Chrome DevTools Protocol. +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 -insecure-http-parser -Use an insecure HTTP parser that accepts invalid HTTP headers. This may allow -interoperability with non-conformant HTTP implementations. It may also allow -request smuggling and other HTTP attacks that rely on invalid headers being -accepted. Avoid using this option. +.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. -. -.Pp -This flag is inherited from V8 and is subject to change upstream. It may -disappear in a non-semver-major release. +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 localStorage data. +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. This flag is a no-op unless +Node.js is started with the \fB--experimental-webstorage\fR flag. . .It Fl -max-http-header-size Ns = Ns Ar size -Specify the maximum size of HTTP headers in bytes. Defaults to 16 KiB. +Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB. . .It Fl -napi-modules -This option is a no-op. -It is kept for compatibility. +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 +Disable support for loading a synchronous ES module graph in \fBrequire()\fR. +See Loading ECMAScript modules using \fBrequire()\fR. +. +.It Fl -no-experimental-sqlite +Disable the experimental \fBnode:sqlite\fR module. +. +.It Fl -no-experimental-strip-types +Disable experimental type-stripping for TypeScript files. +For more information, see the TypeScript type-stripping documentation. +. +.It Fl -no-experimental-websocket +Disable exposition of \fBWebSocket\fR on the global scope. +. .It Fl -no-extra-info-on-fatal-exception Hide extra information on fatal exception that causes exit. . .It Fl -no-force-async-hooks-checks -Disable runtime checks for `async_hooks`. -These will still be enabled dynamically when `async_hooks` is enabled. -. -.It Fl -no-addons -Disable the `node-addons` exports condition as well as disable loading native -addons. When `--no-addons` is specified, calling `process.dlopen` or requiring -a native C++ addon will fail and throw an exception. +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. +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-warnings Silence all process warnings (including deprecations). @@ -362,214 +937,433 @@ 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 with -.Sy ./configure --openssl-fips . +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 +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 -preserve-symlinks -Instructs the module loader to preserve symbolic links when resolving and caching modules other than the main module. +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/\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. +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 -.Fl -prof . +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 -.Ar file -instead of printing to stderr. +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 -.Sy diagnostic reports -in a compact format, single-line JSON. -. -.It Fl -report-dir Fl -report-directory -Location at which the -.Sy diagnostic report -will be generated. -The `file` name may be an absolute path. If it is not, the default directory it will -be written to is controlled by the -.Fl -diagnostic-dir . -command-line option. -. -.It Fl -report-filename -Name of the file to which the -.Sy diagnostic report -will be written. +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 eport-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 -.Sy diagnostic report -to be triggered on fatal errors (internal errors within the Node.js runtime such -as out of memory) that leads 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. +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 -.Sy diagnostic report -to be generated upon receiving the specified (or predefined) signal to the -running Node.js process. Default signal is SIGUSR2. +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 -Sets or resets the signal for -.Sy diagnostic report -generation (not supported on Windows). Default signal is SIGUSR2. +.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 -.Sy diagnostic report -to be generated on un-caught exceptions. Useful when inspecting JavaScript -stack in conjunction with native stack and other runtime environment data. +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 -secure-heap Ns = Ns Ar n -Specify the size of the OpenSSL secure heap. Any value less than 2 disables -the secure heap. The default is 0. The value must be a power of two. +.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. +Only CommonJS modules are supported. +Use \fB--import\fR to preload an ECMAScript 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 -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 -Specify the minimum allocation from the OpenSSL secure heap. The default is 2. The value must be a power of two. +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. +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. +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 threshold for branch coverage (0 - 100). +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 -A glob pattern that excludes matching files from the coverage report +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 threshold for function coverage (0 - 100). +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 -A glob pattern that only includes matching files in the coverage report +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 threshold for line coverage (0 - 100). +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-isolation Ns = Ns Ar mode -Configures the type of test isolation used in the test runner. +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. +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-reporter -A test reporter to use when running tests. +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. -. -.It Fl -test-only -Configures the test runner to only execute top level tests that have the `only` -option set. +The destination for the corresponding test reporter. See the documentation on +test reporters for more details. . .It Fl -test-shard -Test suite shard to execute in a format of /. +Test suite shard to execute in a format of \fB/\fR, where +\fBindex\fR is a positive integer, index of divided parts +\fBtotal\fR is a positive integer, total of divided part +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. +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. +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 file used by the test runner for snapshot testing. +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 -Specify process.title on startup. +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) +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 SSLKEYLOGFILE +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 default maxVersion to 'TLSv1.2'. Use to disable support for TLSv1.3. +Set \fBtls.DEFAULT_MAX_VERSION\fR to 'TLSv1.2'. Use to disable support for +TLSv1.3. . .It Fl -tls-max-v1.3 -Set default maxVersion to 'TLSv1.3'. Use to enable support for TLSv1.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 minVersion to 'TLSv1'. Use for compatibility with old TLS clients -or servers. +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 minVersion to 'TLSv1.1'. Use for compatibility with old TLS clients -or servers. +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 minVersion to 'TLSv1.2'. This is the default for 12.x and later, -but the option is supported for compatibility with older Node.js versions. +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 minVersion to 'TLSv1.3'. Use to disable support for TLSv1.2 in -favour of TLSv1.3, which is more secure. +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-event-categories Ar categories -A comma-separated list of categories that should be traced when trace event tracing is enabled using -.Fl -trace-events-enabled . +.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-event-file-pattern Ar pattern +.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 -.Sy ${rotation} -and -.Sy ${pid} . +supports \fB${rotation}\fR and \fB${pid}\fR. . .It Fl -trace-events-enabled -Enable the collection of trace event tracing information. +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 `process.exit()`. +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 -Print a stack trace whenever synchronous I/O is detected after the first turn of the event loop. +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 stderr. +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 -.Sy Error -is printed, whereas this makes Node.js also +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 -.Sy Error -instance). -.Pp +to be an \fBError\fR instance). Enabling this option may affect garbage collection behavior negatively. . .It Fl -trace-warnings @@ -578,238 +1372,740 @@ Print stack traces for process warnings (including deprecations). .It Fl -track-heap-objects Track heap object allocations for heap snapshots. . -.It Fl -unhandled-rejections=mode -Define the behavior for unhandled rejections. Can be one of `strict` (raise an error), `warn` (enforce warnings) or `none` (silence warnings). +.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. -.Pp -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. -.Pp -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. -.Pp -See -.Ev SSL_CERT_DIR -and -.Ev SSL_CERT_FILE . +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-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. -.Pp -.Ar mode -must have one of the following values: -`off` (the default value, meaning do not map), `on` (map and ignore failure, -reporting it to stderr), or `silent` (map and silently ignore failure). +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 planned to follow +Chromium's policy for locally trusted certificates: +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 +Distrust:.Bl -bullet +.It +Any certificate where the “When using this certificate” flag is set to “Never Trust” or +.It +Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Never Trust.” +.El +.El +.El +On Windows, the following settings are respected (unlike Chromium's policy, distrust +and intermediate CA are not currently supported): +.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 certificates +do not forbid them for TLS server authentication before using them. +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 0 then V8 will choose an appropriate size of the thread pool based on the number of online processors. -If the value provided is larger than V8's maximum, then the largest value will be chosen. +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 -zero-fill-buffers -Automatically zero-fills all newly allocated Buffer and SlowBuffer instances. +.It Fl v , Fl -version +Print node's version. . -.It Fl c , Fl -check -Check the script's syntax without executing it. -Exits with an error code if script is invalid. +.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. +.Bd -literal +node --watch index.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. +.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 e , Fl -eval Ar string -Evaluate -.Ar string -as JavaScript. +.It Fl -zero-fill-buffers +Automatically zero-fills all newly allocated \fBBuffer\fR and \fBSlowBuffer\fR +instances. . -.It Fl h , Fl -help -Print command-line options. -The output of this option is less detailed than this document. + +.El . -.It Fl i , Fl -interactive -Open the REPL even if stdin does not appear to be a terminal. +.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 Fl p , Fl -print Ar string -Identical to -.Fl e , -but prints the result. +.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 Fl r , Fl -require Ar module -Preload the specified -.Ar module -at startup. -Follows `require()`'s module resolution rules. -.Ar module -may be either a path to a file, or a Node.js module name. +.It Ev NODE_DEBUG Ar module[,…] +\fB','\fR-separated list of core modules that should print debug information. . -.It Fl v , Fl -version -Print node's version. -.El +.It Ev NODE_DEBUG_NATIVE Ar module[,…] +\fB','\fR-separated list of core C++ modules that should print debug information. . -.\" ===================================================================== -.Sh ENVIRONMENT -.Bl -tag -width 6n -.It Ev FORCE_COLOR -Used to enable ANSI colorized output. The value may be one of: -.Ar 1 -, -.Ar true -, or -.Ar an empty string -to -indicate 16-color support, -.Ar 2 -to indicate 256-color support, or -.Ar 3 -to indicate 16 million-color support. When used and set to a supported -value, both the NO_COLOR and NODE_DISABLE_COLORS environment variables -are ignored. Any other value will result in colorized output being -disabled. -. -.It Ev NO_COLOR -Alias for NODE_DISABLE_COLORS -. -.It Ev NODE_DEBUG Ar modules... -Comma-separated list of core modules that should print debug information. -. -.It Ev NODE_DEBUG_NATIVE Ar modules... -Comma-separated list of C++ core modules that should print debug information. -. -.It Ev NODE_DISABLE_COLORS -When set to -.Ar 1 , -colors will not be used in the REPL. +.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 -.Dq root -CAs (like VeriSign) will be extended with the extra certificates in -.Ar file . -The file should consist of one or more trusted certificates in PEM format. -.Pp -If -.Ar file -is missing or misformatted, a message will be emitted once using -.Sy process.emitWarning() , -but any errors are otherwise ignored. -.Pp -This environment variable is ignored when `node` runs as setuid root or +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. -.Pp -The -.Ar NODE_EXTRA_CA_CERTS -environment variable is only read when the Node.js process is first launched. -Changing the value at runtime using -.Ar process.env.NODE_EXTRA_CA_CERTS -has no effect on the current process. +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 (Intl object) data. -Will extend linked-in data when compiled with small-icu support. +Data path for ICU (\fBIntl\fR object) data. Will extend linked-in data when compiled +with small-icu support. . -.It Ev NODE_NO_WARNINGS -When set to -.Ar 1 , -process warnings are silenced. +.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 -.Ar options , -which are interpreted as if they had been specified on the command line before the actual command (so they can be overridden). -Node.js will exit with an error if an option that is not allowed in the environment is used, such as -.Fl -print -or a script file. -. -.It Ev NODE_PATH Ar directories... -A colon-separated list of -.Ar directories -prefixed to the module search path. -. -.It Ev NODE_PENDING_DEPRECATION -When set to -.Ar 1 , -emit pending deprecation warnings. -. -.It Ev NODE_PRESERVE_SYMLINKS -When set to -.Ar 1 , -the module loader preserves symbolic links when resolving and caching modules. +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-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-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-transform-types\fR +.It +\fB--experimental-vm-modules\fR +.It +\fB--experimental-wasi-unstable-preview1\fR +.It +\fB--experimental-wasm-modules\fR +.It +\fB--experimental-webstorage\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--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-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-warnings\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--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\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-isolation\fR +.It +\fB--test-name-pattern\fR +.It +\fB--test-only\fR +.It +\fB--test-reporter-destination\fR +.It +\fB--test-reporter\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-largepages\fR +.It +\fB--use-openssl-ca\fR +.It +\fB--use-system-ca\fR +.It +\fB--v8-pool-size\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 -Write process warnings to the given -.Ar file -instead of printing to stderr. -Equivalent to passing -.Fl -redirect-warnings Ar file -on the command line. -. -.It Ev NODE_REPL_HISTORY Ar file -Path to the -.Ar file -used to store persistent REPL history. -The default path is -.Sy ~/.node_repl_history , -which is overridden by this variable. -Setting the value to an empty string ("" or " ") will disable persistent REPL history. +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 (`''`) will use the built-in REPL. -. -.It Ev NODE_SKIP_PLATFORM_CHECK -When set to -.Ar 1 , -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. +Overriding this value to an empty string (\fB''\fR) will use the built-in REPL. . -.It Ev NODE_TLS_REJECT_UNAUTHORIZED -When set to -.Ar 0 , -TLS certificate validation is disabled. +.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 currently only affects requests sent over \fBfetch()\fR. Support for other +built-in \fBhttp\fR and \fBhttps\fR methods is under way. . .It Ev NODE_V8_COVERAGE Ar dir -When set, Node.js writes JavaScript code coverage information to -.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 +\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 -.Sy ./configure --openssl-fips . -.Pp -If the -.Fl -openssl-config -command-line option is used, this environment variable is ignored. +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 -.Fl -use-openssl-ca -is enabled, this overrides and sets OpenSSL's directory containing trusted certificates. +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 -.Fl -use-openssl-ca -is enabled, this overrides and sets OpenSSL's file containing trusted certificates. +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 -Specify the timezone configuration. +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 -Sets the number of threads used in libuv's threadpool to -.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 guranteed 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. @@ -820,7 +2116,6 @@ See .Sy https://github.com/nodejs/node/blob/HEAD/LICENSE for the full license text. . -.\"====================================================================== .Sh SEE ALSO Website: .Sy https://nodejs.org/ diff --git a/test/parallel/test-cli-node-options-docs.js b/test/parallel/test-cli-node-options-docs.js index f3034ef64bc5a9..b63f01770f9966 100644 --- a/test/parallel/test-cli-node-options-docs.js +++ b/test/parallel/test-cli-node-options-docs.js @@ -22,22 +22,12 @@ const addOptionRE = /AddOption[\s\n\r]*\([\s\n\r]*"([^"]+)"(.*?)\);/gs; const nodeOptionsText = cliText.match(/(.*)/s)[1]; const v8OptionsText = cliText.match(/(.*)/s)[1]; -const manPage = path.join(rootDir, 'doc', 'node.1'); -const manPageText = fs.readFileSync(manPage, { encoding: 'utf8' }); - // Documented in /doc/api/deprecations.md const deprecated = [ '--debug', '--debug-brk', ]; - -const manPagesOptions = new Set(); - -for (const [, envVar] of manPageText.matchAll(/\.It Fl (-[a-zA-Z0-9._-]+)/g)) { - manPagesOptions.add(envVar); -} - for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { let hasTrueAsDefaultValue = false; let isInNodeOption = false; @@ -68,14 +58,11 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { deprecated.includes(envVar) || isNoOp ) { - // assert(!manPagesOptions.has(envVar.slice(1)), `Option ${envVar} should not be documented`) - manPagesOptions.delete(envVar.slice(1)); continue; } // Internal API options are documented in /doc/contributing/internal-api.md if (new RegExp(`####.*\`${envVar}[[=\\s\\b\`]`).test(internalApiText) === true) { - manPagesOptions.delete(envVar.slice(1)); continue; } @@ -83,8 +70,6 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { if (!isV8Option && !hasTrueAsDefaultValue) { if (new RegExp(`###.*\`${envVar}[[=\\s\\b\`]`).test(cliText) === false) { assert(false, `Should have option ${envVar} documented`); - } else { - manPagesOptions.delete(envVar.slice(1)); } } @@ -95,8 +80,6 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { if (!isV8Option && hasTrueAsDefaultValue) { if (new RegExp(`###.*\`--no${envVar.slice(1)}[[=\\s\\b\`]`).test(cliText) === false) { assert(false, `Should have option --no${envVar.slice(1)} documented`); - } else { - manPagesOptions.delete(`-no${envVar.slice(1)}`); } } @@ -118,8 +101,6 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { if (isV8Option) { if (new RegExp(`###.*\`${envVar}[[=\\s\\b\`]`).test(v8OptionsText) === false) { assert(false, `Should have option ${envVar} in V8 options documented`); - } else { - manPagesOptions.delete(envVar.slice(1)); } } } @@ -138,8 +119,3 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { previousIndex = match?.index; } while (match); } - -// add alias handling -manPagesOptions.delete('-trace-events-enabled'); - -assert.strictEqual(manPagesOptions.size, 0, `Man page options not documented: ${[...manPagesOptions]}`); diff --git a/tools/lint-md/lint-md.mjs b/tools/lint-md/lint-md.mjs index f8e29f313644f1..fbc42ff11d4f9e 100644 --- a/tools/lint-md/lint-md.mjs +++ b/tools/lint-md/lint-md.mjs @@ -1,5 +1,6 @@ import fs from 'node:fs'; import { parseArgs } from 'node:util'; +import { resolve, join } from 'node:path'; import { unified } from 'unified'; import remarkParse from 'remark-parse'; @@ -8,6 +9,8 @@ import presetLintNode from 'remark-preset-lint-node'; import { read } from 'to-vfile'; import { reporter } from 'vfile-reporter'; +import generateManPage from './man-page.mjs'; + const { values: { format }, positionals: paths } = parseArgs({ options: { format: { type: 'boolean', default: false }, @@ -20,6 +23,16 @@ if (!paths.length) { process.exit(1); } +const rootDir = resolve(import.meta.dirname, '..', '..'); +const cliPath = resolve(join(rootDir, 'doc', 'api', 'cli.md')); +const manPagePath = join(rootDir, 'doc', 'node.1'); + +function handleDifference(filePath) { + process.exitCode = 1; + const buildCmd = process.platform === 'win32' ? 'vcbuild' : 'make'; + console.error(`${filePath} is not formatted. Please run '${buildCmd} format-md'.`); +} + const linter = unified() .use(remarkParse) .use(presetLintNode) @@ -42,16 +55,24 @@ paths.forEach(async (path) => { } } + let isManPageModified = false; + let generatedManPage; + if (resolve(path) === cliPath) { + generatedManPage = await generateManPage(path); + const oldManPage = fs.readFileSync(manPagePath, 'utf-8'); + isManPageModified = oldManPage !== generatedManPage; + } + if (format) { if (isDifferent) { fs.writeFileSync(path, result.toString()); } - } else { - if (isDifferent) { - process.exitCode = 1; - const cmd = process.platform === 'win32' ? 'vcbuild' : 'make'; - console.error(`${path} is not formatted. Please run '${cmd} format-md'.`); + if (isManPageModified) { + fs.writeFileSync(manPagePath, generatedManPage); } + } else { + if (isDifferent) handleDifference(path); + if (isManPageModified) handleDifference('doc/node.1'); if (result.messages.length) { process.exitCode = 1; console.error(reporter(result)); diff --git a/tools/lint-md/man-page.mjs b/tools/lint-md/man-page.mjs new file mode 100644 index 00000000000000..4671c97cfedf03 --- /dev/null +++ b/tools/lint-md/man-page.mjs @@ -0,0 +1,8 @@ +import { generators, createParser } from '@node-core/api-docs-tooling'; +import { read } from 'to-vfile'; + +export default async function generateManPage(path) { + const { parseApiDocs } = createParser(); + const parsedApiDocs = await parseApiDocs([read(path)]); + return generators['man-page'].generate(parsedApiDocs, {}); +} diff --git a/tools/lint-md/package-lock.json b/tools/lint-md/package-lock.json index 75355b8c78c6c7..59710c145cb769 100644 --- a/tools/lint-md/package-lock.json +++ b/tools/lint-md/package-lock.json @@ -8,6 +8,7 @@ "name": "lint-md", "version": "1.0.0", "dependencies": { + "@node-core/api-docs-tooling": "github:nodejs/api-docs-tooling#f51c583fc7db6af2590072ffebaedd86cff97d04", "remark-parse": "^11.0.0", "remark-preset-lint-node": "^5.1.2", "remark-stringify": "^11.0.0", @@ -16,6 +17,252 @@ "vfile-reporter": "^8.1.1" } }, + "node_modules/@actions/core": { + "version": "1.11.1", + "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.11.1.tgz", + "integrity": "sha512-hXJCSrkwfA46Vd9Z3q4cpEpHB1rL5NG04+/rbqW9d3+CSvtB1tYe8UTpAlixa1vj0m/ULglfEK2UKxMGxCxv5A==", + "license": "MIT", + "dependencies": { + "@actions/exec": "^1.1.1", + "@actions/http-client": "^2.0.1" + } + }, + "node_modules/@actions/exec": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@actions/exec/-/exec-1.1.1.tgz", + "integrity": "sha512-+sCcHHbVdk93a0XT19ECtO/gIXoxvdsgQLzb2fE2/5sIZmWQuluYyjPQtrtTHdU1YzTZ7bAPN4sITq2xi1679w==", + "license": "MIT", + "dependencies": { + "@actions/io": "^1.0.1" + } + }, + "node_modules/@actions/http-client": { + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.2.3.tgz", + "integrity": "sha512-mx8hyJi/hjFvbPokCg4uRd4ZX78t+YyRPtnKWwIl+RzNaVuFpQHfmlGVfsKEJN8LwTCvL+DfVgAM04XaHkm6bA==", + "license": "MIT", + "dependencies": { + "tunnel": "^0.0.6", + "undici": "^5.25.4" + } + }, + "node_modules/@actions/io": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@actions/io/-/io-1.1.3.tgz", + "integrity": "sha512-wi9JjgKLYS7U/z8PPbco+PvTb/nRWjeoFlJ1Qer83k/3C5PHQi28hiVdeE2kHXmIL99mQFawx8qt/JPjZilJ8Q==", + "license": "MIT" + }, + "node_modules/@fastify/busboy": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz", + "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==", + "license": "MIT", + "engines": { + "node": ">=14" + } + }, + "node_modules/@isaacs/cliui": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", + "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==", + "license": "ISC", + "dependencies": { + "string-width": "^5.1.2", + "string-width-cjs": "npm:string-width@^4.2.0", + "strip-ansi": "^7.0.1", + "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", + "wrap-ansi": "^8.1.0", + "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@isaacs/cliui/node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "license": "MIT" + }, + "node_modules/@isaacs/cliui/node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.5", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.5.tgz", + "integrity": "sha512-IzL8ZoEDIBRWEzlCcRhOaCupYyN5gdIK+Q6fbFdPDg6HqX6jpkItn7DFIpW9LQzXG6Df9sA7+OKnq0qlz/GaQg==", + "license": "MIT", + "dependencies": { + "@jridgewell/set-array": "^1.2.1", + "@jridgewell/sourcemap-codec": "^1.4.10", + "@jridgewell/trace-mapping": "^0.3.24" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/set-array": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@jridgewell/set-array/-/set-array-1.2.1.tgz", + "integrity": "sha512-R8gLRTZeyp03ymzP/6Lil/28tGeGEzhx1q2k703KGWRAI1VdvPIXdG70VJc2pAMw3NA6JKL5hhFu1sJX0Mnn/A==", + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/source-map": { + "version": "0.3.6", + "resolved": "https://registry.npmjs.org/@jridgewell/source-map/-/source-map-0.3.6.tgz", + "integrity": "sha512-1ZJTZebgqllO79ue2bm3rIGud/bOe0pP5BjSRCRxxYkEZS8STV7zN84UBbiYu7jy+eCKSnVIUgoWWE/tt+shMQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.5", + "@jridgewell/trace-mapping": "^0.3.25" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.0.tgz", + "integrity": "sha512-gv3ZRaISU3fjPAgNsriBRqGWQL6quFx04YMPW/zD8XMLsU32mhCCbfbO6KZFLjvYpCZ8zyDEgqsgf+PwPaM7GQ==", + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.25", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.25.tgz", + "integrity": "sha512-vNk6aEwybGtawWmy/PzwnGDOjCkLWSD2wqvjGGAgOAwCGWySYXfYoxt00IJkTF+8Lb57DwOb3Aa0o9CApepiYQ==", + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@node-core/api-docs-tooling": { + "resolved": "git+ssh://git@github.com/nodejs/api-docs-tooling.git#f51c583fc7db6af2590072ffebaedd86cff97d04", + "integrity": "sha512-u2puPDsEjFAl1DdA2ObF42E6JFgQTeEkRtd/ol8Hbk9TiySoadxNBxRoH2nXR9J5g34SnptgHnRhaLKgNB830A==", + "dependencies": { + "@actions/core": "^1.11.1", + "acorn": "^8.14.0", + "commander": "^13.1.0", + "dedent": "^1.5.3", + "estree-util-visit": "^2.0.0", + "github-slugger": "^2.0.0", + "glob": "^11.0.1", + "hast-util-to-string": "^3.0.1", + "hastscript": "^9.0.1", + "html-minifier-terser": "^7.2.0", + "rehype-stringify": "^10.0.1", + "remark-gfm": "^4.0.1", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.1.1", + "remark-stringify": "^11.0.0", + "semver": "^7.7.1", + "shiki": "^2.2.0", + "unified": "^11.0.5", + "unist-builder": "^4.0.0", + "unist-util-find-after": "^5.0.0", + "unist-util-position": "^5.0.0", + "unist-util-remove": "^4.0.0", + "unist-util-select": "^5.1.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.3", + "yaml": "^2.7.0" + }, + "bin": { + "api-docs-tooling": "bin/cli.mjs" + } + }, + "node_modules/@shikijs/core": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-2.5.0.tgz", + "integrity": "sha512-uu/8RExTKtavlpH7XqnVYBrfBkUc20ngXiX9NSrBhOVZYv/7XQRKUyhtkeflY5QsxC0GbJThCerruZfsUaSldg==", + "license": "MIT", + "dependencies": { + "@shikijs/engine-javascript": "2.5.0", + "@shikijs/engine-oniguruma": "2.5.0", + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.4" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-2.5.0.tgz", + "integrity": "sha512-VjnOpnQf8WuCEZtNUdjjwGUbtAVKuZkVQ/5cHy/tojVVRIRtlWMYVjyWhxOmIq05AlSOv72z7hRNRGVBgQOl0w==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "oniguruma-to-es": "^3.1.0" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-2.5.0.tgz", + "integrity": "sha512-pGd1wRATzbo/uatrCIILlAdFVKdxImWJGQ5rFiB5VZi2ve5xj3Ax9jny8QvkaV93btQEwR/rSz5ERFpC5mKNIw==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-2.5.0.tgz", + "integrity": "sha512-Qfrrt5OsNH5R+5tJ/3uYBBZv3SuGmnRPejV9IlIbFH3HTGLDlkqgHymAlzklVmKBjAaVmkPkyikAV/sQ1wSL+w==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-2.5.0.tgz", + "integrity": "sha512-wGrk+R8tJnO0VMzmUExHR+QdSaPUl/NKs+a4cQQRWyoc3YFbUzuLEi/KWK1hj+8BfHRKm2jNhhJck1dfstJpiw==", + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0" + } + }, + "node_modules/@shikijs/types": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-2.5.0.tgz", + "integrity": "sha512-ygl5yhxki9ZLNuNpPitBWvcy9fsSKKaRuO4BAlMyagszQidxcpLAr0qiW/q43DtSIDxO6hEbtYLiFZNXO/hdGw==", + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "license": "MIT" + }, "node_modules/@types/debug": { "version": "4.1.12", "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", @@ -76,6 +323,24 @@ "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", "license": "MIT" }, + "node_modules/@ungap/structured-clone": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.2.0.tgz", + "integrity": "sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==", + "license": "ISC" + }, + "node_modules/acorn": { + "version": "8.14.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.0.tgz", + "integrity": "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA==", + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, "node_modules/ansi-regex": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.1.0.tgz", @@ -88,6 +353,18 @@ "url": "https://github.com/chalk/ansi-regex?sponsor=1" } }, + "node_modules/ansi-styles": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -104,6 +381,43 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "license": "MIT" + }, + "node_modules/boolbase": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", + "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==", + "license": "ISC" + }, + "node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/buffer-from": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", + "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", + "license": "MIT" + }, + "node_modules/camel-case": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/camel-case/-/camel-case-4.1.2.tgz", + "integrity": "sha512-gxGWBrTT1JuMx6R+o5PTXMmUnhnVzLQ9SNutD4YqKtI6ap897t3tKECYla6gCWEkplXnlNybEkZg9GEGxKFCgw==", + "license": "MIT", + "dependencies": { + "pascal-case": "^3.1.2", + "tslib": "^2.0.3" + } + }, "node_modules/ccount": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", @@ -154,6 +468,18 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/clean-css": { + "version": "5.3.3", + "resolved": "https://registry.npmjs.org/clean-css/-/clean-css-5.3.3.tgz", + "integrity": "sha512-D5J+kHaVb/wKSFcyyV75uCn8fiY4sV38XJoe4CUyGQ+mOU/fMVYUdH1hJC+CJQ5uY3EnW27SbJYS4X8BiLrAFg==", + "license": "MIT", + "dependencies": { + "source-map": "~0.6.0" + }, + "engines": { + "node": ">= 10.0" + } + }, "node_modules/collapse-white-space": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/collapse-white-space/-/collapse-white-space-2.1.0.tgz", @@ -164,6 +490,73 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "license": "MIT" + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/commander": { + "version": "13.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz", + "integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==", + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/css-selector-parser": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/css-selector-parser/-/css-selector-parser-3.0.5.tgz", + "integrity": "sha512-3itoDFbKUNx1eKmVpYMFyqKX04Ww9osZ+dLgrk6GEv6KMVeXUhUnp4I5X+evw+u3ZxVU6RFXSSRxlTeMh8bA+g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/mdevils" + }, + { + "type": "patreon", + "url": "https://patreon.com/mdevils" + } + ], + "license": "MIT" + }, "node_modules/debug": { "version": "4.3.7", "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.7.tgz", @@ -194,6 +587,20 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/dedent": { + "version": "1.5.3", + "resolved": "https://registry.npmjs.org/dedent/-/dedent-1.5.3.tgz", + "integrity": "sha512-NHQtfOOW68WD8lgypbLA5oT+Bt0xXJhiYvoR6SmmNXZfpzOGXwdKWmcwG8N7PwVVWV3eF/68nmD9BaJSsTBhyQ==", + "license": "MIT", + "peerDependencies": { + "babel-plugin-macros": "^3.1.0" + }, + "peerDependenciesMeta": { + "babel-plugin-macros": { + "optional": true + } + } + }, "node_modules/dequal": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", @@ -216,6 +623,16 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/dot-case": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/dot-case/-/dot-case-3.0.4.tgz", + "integrity": "sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==", + "license": "MIT", + "dependencies": { + "no-case": "^3.0.4", + "tslib": "^2.0.3" + } + }, "node_modules/eastasianwidth": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz", @@ -228,6 +645,24 @@ "integrity": "sha512-EC+0oUMY1Rqm4O6LLrgjtYDvcVYTy7chDnM4Q7030tP4Kwj3u/pR6gP9ygnp2CJMK5Gq+9Q2oqmrFJAz01DXjw==", "license": "MIT" }, + "node_modules/emoji-regex-xs": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex-xs/-/emoji-regex-xs-1.0.0.tgz", + "integrity": "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==", + "license": "MIT" + }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/escape-string-regexp": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", @@ -240,12 +675,190 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/estree-util-visit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz", + "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==", + "license": "MIT", + "dependencies": { + "@types/estree-jsx": "^1.0.0", + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/extend": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", "license": "MIT" }, + "node_modules/foreground-child": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz", + "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==", + "license": "ISC", + "dependencies": { + "cross-spawn": "^7.0.6", + "signal-exit": "^4.0.1" + }, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/github-slugger": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz", + "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==", + "license": "ISC" + }, + "node_modules/glob": { + "version": "11.0.1", + "resolved": "https://registry.npmjs.org/glob/-/glob-11.0.1.tgz", + "integrity": "sha512-zrQDm8XPnYEKawJScsnM0QzobJxlT/kHOOlRTio8IH/GrmxRE5fjllkzdaHclIuNjUQTJYH2xHNIGfdpJkDJUw==", + "license": "ISC", + "dependencies": { + "foreground-child": "^3.1.0", + "jackspeak": "^4.0.1", + "minimatch": "^10.0.0", + "minipass": "^7.1.2", + "package-json-from-dist": "^1.0.0", + "path-scurry": "^2.0.0" + }, + "bin": { + "glob": "dist/esm/bin.mjs" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/hast-util-parse-selector": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz", + "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz", + "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-string": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz", + "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hastscript": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.1.tgz", + "integrity": "sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-parse-selector": "^4.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/html-minifier-terser": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/html-minifier-terser/-/html-minifier-terser-7.2.0.tgz", + "integrity": "sha512-tXgn3QfqPIpGl9o+K5tpcj3/MN4SfLtsx2GWwBC3SSd0tXQGyF3gsSqad8loJgKZGM3ZxbYDd5yhiBIdWpmvLA==", + "license": "MIT", + "dependencies": { + "camel-case": "^4.1.2", + "clean-css": "~5.3.2", + "commander": "^10.0.0", + "entities": "^4.4.0", + "param-case": "^3.0.4", + "relateurl": "^0.2.7", + "terser": "^5.15.1" + }, + "bin": { + "html-minifier-terser": "cli.js" + }, + "engines": { + "node": "^14.13.1 || >=16.0.0" + } + }, + "node_modules/html-minifier-terser/node_modules/commander": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/commander/-/commander-10.0.1.tgz", + "integrity": "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==", + "license": "MIT", + "engines": { + "node": ">=14" + } + }, + "node_modules/html-void-elements": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/is-alphabetical": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", @@ -303,6 +916,15 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/is-hexadecimal": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", @@ -325,6 +947,27 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/jackspeak": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.1.0.tgz", + "integrity": "sha512-9DDdhb5j6cpeitCbvLO7n7J4IxnbM6hoF6O1g4HQ5TfhvvKN8ywDM7668ZhMHRqVmxqhps/F6syWK2KcPxYlkw==", + "license": "BlueOak-1.0.0", + "dependencies": { + "@isaacs/cliui": "^8.0.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/js-yaml": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", @@ -347,6 +990,24 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/lower-case": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/lower-case/-/lower-case-2.0.2.tgz", + "integrity": "sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==", + "license": "MIT", + "dependencies": { + "tslib": "^2.0.3" + } + }, + "node_modules/lru-cache": { + "version": "11.0.2", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.0.2.tgz", + "integrity": "sha512-123qHRfJBmo2jXDbo/a5YOQrJoHF/GNQTLzQ5+IdK5pWpceK17yRc6ozlWd25FxvGKQbIUs91fDFkXmDHTKcyA==", + "license": "ISC", + "engines": { + "node": "20 || >=22" + } + }, "node_modules/markdown-table": { "version": "3.0.4", "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz", @@ -636,6 +1297,27 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz", + "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/mdast-util-to-markdown": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.0.tgz", @@ -1232,12 +1914,85 @@ ], "license": "MIT" }, + "node_modules/minimatch": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.0.1.tgz", + "integrity": "sha512-ethXTt3SGGR+95gudmqJ1eNhRO7eGEGIgYA9vnPatK4/etz2MEVDno5GMCibdMTuBMyElzIlgxMna3K94XDIDQ==", + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/minipass": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.2.tgz", + "integrity": "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw==", + "license": "ISC", + "engines": { + "node": ">=16 || 14 >=14.17" + } + }, "node_modules/ms": { "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", "license": "MIT" }, + "node_modules/no-case": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/no-case/-/no-case-3.0.4.tgz", + "integrity": "sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==", + "license": "MIT", + "dependencies": { + "lower-case": "^2.0.2", + "tslib": "^2.0.3" + } + }, + "node_modules/nth-check": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", + "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==", + "license": "BSD-2-Clause", + "dependencies": { + "boolbase": "^1.0.0" + }, + "funding": { + "url": "https://github.com/fb55/nth-check?sponsor=1" + } + }, + "node_modules/oniguruma-to-es": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-3.1.1.tgz", + "integrity": "sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==", + "license": "MIT", + "dependencies": { + "emoji-regex-xs": "^1.0.0", + "regex": "^6.0.1", + "regex-recursion": "^6.0.2" + } + }, + "node_modules/package-json-from-dist": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz", + "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==", + "license": "BlueOak-1.0.0" + }, + "node_modules/param-case": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/param-case/-/param-case-3.0.4.tgz", + "integrity": "sha512-RXlj7zCYokReqWpOPH9oYivUzLYZ5vAPIfEmCTNViosC78F8F0H9y7T7gG2M39ymgutxF5gcFEsyZQSph9Bp3A==", + "license": "MIT", + "dependencies": { + "dot-case": "^3.0.4", + "tslib": "^2.0.3" + } + }, "node_modules/parse-entities": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.1.tgz", @@ -1264,13 +2019,58 @@ "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", "license": "MIT" }, + "node_modules/pascal-case": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/pascal-case/-/pascal-case-3.1.2.tgz", + "integrity": "sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g==", + "license": "MIT", + "dependencies": { + "no-case": "^3.0.4", + "tslib": "^2.0.3" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-scurry": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.0.tgz", + "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==", + "license": "BlueOak-1.0.0", + "dependencies": { + "lru-cache": "^11.0.0", + "minipass": "^7.1.2" + }, + "engines": { + "node": "20 || >=22" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/pluralize": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/pluralize/-/pluralize-8.0.0.tgz", "integrity": "sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==", "license": "MIT", - "engines": { - "node": ">=4" + "engines": { + "node": ">=4" + } + }, + "node_modules/property-information": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.0.0.tgz", + "integrity": "sha512-7D/qOz/+Y4X/rzSB6jKxKUsQnphO046ei8qxG59mtM3RG3DHgTK81HrxrmoDVINJb8NKT5ZsRbwHvQ6B68Iyhg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" } }, "node_modules/quotation": { @@ -1283,10 +2083,58 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/regex": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.0.1.tgz", + "integrity": "sha512-uorlqlzAKjKQZ5P+kTJr3eeJGSVroLKoHmquUj4zHWuR+hEyNqlXsSKlYYF5F4NI6nl7tWCs0apKJ0lmfsXAPA==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "license": "MIT" + }, + "node_modules/rehype-stringify": { + "version": "10.0.1", + "resolved": "https://registry.npmjs.org/rehype-stringify/-/rehype-stringify-10.0.1.tgz", + "integrity": "sha512-k9ecfXHmIPuFVI61B9DeLPN0qFHfawM6RsuX48hoqlaKSF61RskNjSm1lI8PhBEM0MRdLxVVm4WmTqJQccH9mA==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "hast-util-to-html": "^9.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/relateurl": { + "version": "0.2.7", + "resolved": "https://registry.npmjs.org/relateurl/-/relateurl-0.2.7.tgz", + "integrity": "sha512-G08Dxvm4iDN3MLM0EsP62EDV9IuhXPR6blNz6Utcp7zyV3tr4HVNINt6MpaRWbxoOHT3Q7YN2P+jaHX8vUbgog==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, "node_modules/remark-gfm": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.0.tgz", - "integrity": "sha512-U92vJgBPkbw4Zfu/IiW2oTZLSL3Zpv+uI7My2eq8JxKgqraFdU8YUGicEJCEgSbeaG+QDFqIcwwfMTOEelPxuA==", + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz", + "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==", "license": "MIT", "dependencies": { "@types/mdast": "^4.0.0", @@ -2209,6 +3057,23 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/remark-rehype": { + "version": "11.1.1", + "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.1.tgz", + "integrity": "sha512-g/osARvjkBXb6Wo0XvAeXQohVta8i84ACbenPpoSsxTOQH/Ae0/RGP4WZgnMH5pMLpsj4FG7OHmcIcXxpza8eQ==", + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "mdast-util-to-hast": "^13.0.0", + "unified": "^11.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/remark-stringify": { "version": "11.0.0", "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz", @@ -2225,9 +3090,9 @@ } }, "node_modules/semver": { - "version": "7.6.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.6.3.tgz", - "integrity": "sha512-oVekP1cKtI+CTDvHWYFUcMtsK/00wmAEfyqKfNdARm8u1wNVhSgaX7A8d4UuIlUI5e84iEwOhs7ZPYRmzU9U6A==", + "version": "7.7.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.1.tgz", + "integrity": "sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA==", "license": "ISC", "bin": { "semver": "bin/semver.js" @@ -2236,6 +3101,74 @@ "node": ">=10" } }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/shiki": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-2.5.0.tgz", + "integrity": "sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==", + "license": "MIT", + "dependencies": { + "@shikijs/core": "2.5.0", + "@shikijs/engine-javascript": "2.5.0", + "@shikijs/engine-oniguruma": "2.5.0", + "@shikijs/langs": "2.5.0", + "@shikijs/themes": "2.5.0", + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/source-map-support": { + "version": "0.5.21", + "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz", + "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==", + "license": "MIT", + "dependencies": { + "buffer-from": "^1.0.0", + "source-map": "^0.6.0" + } + }, "node_modules/space-separated-tokens": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", @@ -2263,6 +3196,48 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/string-width-cjs": { + "name": "string-width", + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/string-width-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/string-width-cjs/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/stringify-entities": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", @@ -2292,6 +3267,28 @@ "url": "https://github.com/chalk/strip-ansi?sponsor=1" } }, + "node_modules/strip-ansi-cjs": { + "name": "strip-ansi", + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/supports-color": { "version": "9.4.0", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-9.4.0.tgz", @@ -2304,6 +3301,30 @@ "url": "https://github.com/chalk/supports-color?sponsor=1" } }, + "node_modules/terser": { + "version": "5.36.0", + "resolved": "https://registry.npmjs.org/terser/-/terser-5.36.0.tgz", + "integrity": "sha512-IYV9eNMuFAV4THUspIRXkLakHnV6XO7FEdtKjf/mDyrnqUg9LnlOn6/RwRvM9SZjR4GUq8Nk8zj67FzVARr74w==", + "license": "BSD-2-Clause", + "dependencies": { + "@jridgewell/source-map": "^0.3.3", + "acorn": "^8.8.2", + "commander": "^2.20.0", + "source-map-support": "~0.5.20" + }, + "bin": { + "terser": "bin/terser" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/terser/node_modules/commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "license": "MIT" + }, "node_modules/to-vfile": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/to-vfile/-/to-vfile-8.0.0.tgz", @@ -2317,6 +3338,16 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/trough": { "version": "2.2.0", "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz", @@ -2327,6 +3358,33 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/tslib": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", + "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", + "license": "0BSD" + }, + "node_modules/tunnel": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz", + "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==", + "license": "MIT", + "engines": { + "node": ">=0.6.11 <=0.7.0 || >=0.7.3" + } + }, + "node_modules/undici": { + "version": "5.29.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-5.29.0.tgz", + "integrity": "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==", + "license": "MIT", + "dependencies": { + "@fastify/busboy": "^2.0.0" + }, + "engines": { + "node": ">=14.0" + } + }, "node_modules/unified": { "version": "11.0.5", "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", @@ -2382,6 +3440,33 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/unist-builder": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-builder/-/unist-builder-4.0.0.tgz", + "integrity": "sha512-wmRFnH+BLpZnTKpc5L7O67Kac89s9HMrtELpnNaE6TAobq5DTZZs5YaTQfAZBA9bFPECx2uVAPO31c+GVug8mg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-find-after": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-find-after/-/unist-util-find-after-5.0.0.tgz", + "integrity": "sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/unist-util-is": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz", @@ -2408,6 +3493,38 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/unist-util-remove": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-remove/-/unist-util-remove-4.0.0.tgz", + "integrity": "sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-select": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-select/-/unist-util-select-5.1.0.tgz", + "integrity": "sha512-4A5mfokSHG/rNQ4g7gSbdEs+H586xyd24sdJqF1IWamqrLHvYb+DH48fzxowyOhOfK7YSqX+XlCojAyuuyyT2A==", + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "css-selector-parser": "^3.0.0", + "devlop": "^1.1.0", + "nth-check": "^2.0.0", + "zwitch": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/unist-util-stringify-position": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", @@ -2540,6 +3657,147 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/wrap-ansi": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz", + "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.1.0", + "string-width": "^5.0.1", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs": { + "name": "wrap-ansi", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/wrap-ansi-cjs/node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi-cjs/node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/wrap-ansi/node_modules/emoji-regex": { + "version": "9.2.2", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz", + "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", + "license": "MIT" + }, + "node_modules/wrap-ansi/node_modules/string-width": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz", + "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==", + "license": "MIT", + "dependencies": { + "eastasianwidth": "^0.2.0", + "emoji-regex": "^9.2.2", + "strip-ansi": "^7.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/yaml": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.7.0.tgz", + "integrity": "sha512-+hSoy/QHluxmC9kCIJyL/uyFmLmc+e5CFR5Wa+bpIhIj85LVb9ZH2nVnqrHoSvKogwODv0ClqZkmiSSaIH5LTA==", + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/zwitch": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", diff --git a/tools/lint-md/package.json b/tools/lint-md/package.json index f7272f493d67a7..babf7305aa03c1 100644 --- a/tools/lint-md/package.json +++ b/tools/lint-md/package.json @@ -3,6 +3,7 @@ "description": "markdown linting", "version": "1.0.0", "dependencies": { + "@node-core/api-docs-tooling": "github:nodejs/api-docs-tooling#f51c583fc7db6af2590072ffebaedd86cff97d04", "remark-parse": "^11.0.0", "remark-preset-lint-node": "^5.1.2", "remark-stringify": "^11.0.0", From 8489cd5771dc28268197fe4935ca4ffd54c09a72 Mon Sep 17 00:00:00 2001 From: RedYetiDev <38299977+RedYetiDev@users.noreply.github.com> Date: Sat, 16 Nov 2024 14:43:40 -0500 Subject: [PATCH 2/3] fixup! cli: generate man-page --- doc/node.1 | 2130 +--------------------------------------------------- 1 file changed, 1 insertion(+), 2129 deletions(-) diff --git a/doc/node.1 b/doc/node.1 index 89aa1fee9e5c8a..66708b1943e6ca 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1,2129 +1 @@ -.\" -.\" This file was generated automatically by the api-docs-tooling 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 | Fl e Ar string | Fl - -.Op Ar arguments ... -. -.Nm node -.Cm inspect, -.Op Ar | Fl e Ar string | Ar : -.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. (/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 -Unlike \fBchild_process.spawn\fR, the \fBchild_process.fork\fR API copies the execution -arguments from the parent process. This means that if you start Node.js with the -Permission Model enabled and include the \fB--allow-child-process\fR flag, calling -\fBchild_process.fork()\fR will propagate all Permission Model flags to the child -process. -. -.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 also needs to be allowed. Consider the following example: -.Bd -literal -$ node --permission index.js - -Error: Access to this API has been restricted - at node:internal/main/run_main_module:23:47 { - code: 'ERR_ACCESS_DENIED', - permission: 'FileSystemRead', - resource: '/Users/rafaelgss/repos/os/node/index.js' -} -.Ed -The process needs to have access to the \fBindex.js\fR module: -.Bd -literal -node --permission --allow-fs-read=/path/to/index.js index.js -.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-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-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. -Currently the support for run-time snapshot is experimental in that: -.Bl -bullet -.It -User-land modules are not yet supported in the snapshot, so only -one single file can be snapshotted. Users can bundle their applications -into a single script with their bundler of choice before building -a snapshot, however. -.It -Only a subset of the built-in modules work in the snapshot, though the -Node.js core test suite checks that a few fairly complex applications -can be snapshotted. Support for more modules are being added. If any -crashes or buggy behaviors occur when building a snapshot, please file -a report in the Node.js issue tracker and link to it in the -tracking issue for user-land snapshots. -.El -. -.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\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\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 will be used as-is; patterns such as -\fB${hhmmss}\fR or \fB${pid}\fR are not supported. -.Bd -literal -$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js -$ ls *.cpuprofile -'CPU.${pid}.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 -int the code compiled from WebAssembly which may speedup 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-network-family-autoselection -Enables the family autoselection algorithm unless connection options explicitly -disables it. -. -.It Fl -enable-source-maps -Enable Source Map v3 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 config -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 config -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-experimental-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 - } -} -.Ed -In the \fBnodeOptions\fR field, only flags that are allowed in \fBNODE_OPTIONS\fR are supported. -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 -.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. -If duplicate keys are present in the configuration file, only -the first key will be used. -The configuration parser will throw an error if the configuration file contains -unknown keys or keys that cannot used in \fBNODE_OPTIONS\fR. -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-loader Ns = Ns Ar module -Specify the \fBmodule\fR containing exported 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-require-module -Supports loading a synchronous ES module graph in \fBrequire()\fR. -See Loading ECMAScript modules using \fBrequire()\fR. -. -.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-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-transform-types -Enables the transformation of TypeScript-only syntax into JavaScript code. -Implies \fB--enable-source-maps\fR. -. -.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-wasm-modules -Enable experimental WebAssembly module support. -. -.It Fl -experimental-webstorage -Enable experimental \fBWeb Storage\fR support. -. -.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-experimental-strip-types\fR. -The default is \fB"commonjs"\fR. -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. This flag is a no-op unless -Node.js is started with the \fB--experimental-webstorage\fR flag. -. -.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 -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 -Disable support for loading a synchronous ES module graph in \fBrequire()\fR. -See Loading ECMAScript modules using \fBrequire()\fR. -. -.It Fl -no-experimental-sqlite -Disable the experimental \fBnode:sqlite\fR module. -. -.It Fl -no-experimental-strip-types -Disable experimental type-stripping for TypeScript files. -For more information, see the TypeScript type-stripping documentation. -. -.It Fl -no-experimental-websocket -Disable exposition of \fBWebSocket\fR on the global scope. -. -.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-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 -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 -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/\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 eport-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. -Only CommonJS modules are supported. -Use \fB--import\fR to preload an ECMAScript 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 -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-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-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-shard -Test suite shard to execute in a format of \fB/\fR, where -\fBindex\fR is a positive integer, index of divided parts -\fBtotal\fR is a positive integer, total of divided part -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-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 planned to follow -Chromium's policy for locally trusted certificates: -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 -Distrust:.Bl -bullet -.It -Any certificate where the “When using this certificate” flag is set to “Never Trust” or -.It -Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Never Trust.” -.El -.El -.El -On Windows, the following settings are respected (unlike Chromium's policy, distrust -and intermediate CA are not currently supported): -.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 certificates -do not forbid them for TLS server authentication before using them. -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. -.Bd -literal -node --watch index.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. -.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 and \fBSlowBuffer\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_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-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-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-transform-types\fR -.It -\fB--experimental-vm-modules\fR -.It -\fB--experimental-wasi-unstable-preview1\fR -.It -\fB--experimental-wasm-modules\fR -.It -\fB--experimental-webstorage\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--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-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-warnings\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--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\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-isolation\fR -.It -\fB--test-name-pattern\fR -.It -\fB--test-only\fR -.It -\fB--test-reporter-destination\fR -.It -\fB--test-reporter\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-largepages\fR -.It -\fB--use-openssl-ca\fR -.It -\fB--use-system-ca\fR -.It -\fB--v8-pool-size\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 currently only affects requests sent over \fBfetch()\fR. Support for other -built-in \fBhttp\fR and \fBhttps\fR methods is under way. -. -.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 -\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 guranteed 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 +FUTURE \ No newline at end of file From 65cad89125ed8f0ebf2fb10f6819a9e334ab1067 Mon Sep 17 00:00:00 2001 From: avivkeller Date: Sun, 23 Mar 2025 13:25:45 -0400 Subject: [PATCH 3/3] rebase --- doc/node.1 | 2130 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 2129 insertions(+), 1 deletion(-) diff --git a/doc/node.1 b/doc/node.1 index 66708b1943e6ca..89aa1fee9e5c8a 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -1 +1,2129 @@ -FUTURE \ No newline at end of file +.\" +.\" This file was generated automatically by the api-docs-tooling 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 | Fl e Ar string | Fl - +.Op Ar arguments ... +. +.Nm node +.Cm inspect, +.Op Ar | Fl e Ar string | Ar : +.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. (/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 +Unlike \fBchild_process.spawn\fR, the \fBchild_process.fork\fR API copies the execution +arguments from the parent process. This means that if you start Node.js with the +Permission Model enabled and include the \fB--allow-child-process\fR flag, calling +\fBchild_process.fork()\fR will propagate all Permission Model flags to the child +process. +. +.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 also needs to be allowed. Consider the following example: +.Bd -literal +$ node --permission index.js + +Error: Access to this API has been restricted + at node:internal/main/run_main_module:23:47 { + code: 'ERR_ACCESS_DENIED', + permission: 'FileSystemRead', + resource: '/Users/rafaelgss/repos/os/node/index.js' +} +.Ed +The process needs to have access to the \fBindex.js\fR module: +.Bd -literal +node --permission --allow-fs-read=/path/to/index.js index.js +.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-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-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. +Currently the support for run-time snapshot is experimental in that: +.Bl -bullet +.It +User-land modules are not yet supported in the snapshot, so only +one single file can be snapshotted. Users can bundle their applications +into a single script with their bundler of choice before building +a snapshot, however. +.It +Only a subset of the built-in modules work in the snapshot, though the +Node.js core test suite checks that a few fairly complex applications +can be snapshotted. Support for more modules are being added. If any +crashes or buggy behaviors occur when building a snapshot, please file +a report in the Node.js issue tracker and link to it in the +tracking issue for user-land snapshots. +.El +. +.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\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\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 will be used as-is; patterns such as +\fB${hhmmss}\fR or \fB${pid}\fR are not supported. +.Bd -literal +$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js +$ ls *.cpuprofile +'CPU.${pid}.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 +int the code compiled from WebAssembly which may speedup 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-network-family-autoselection +Enables the family autoselection algorithm unless connection options explicitly +disables it. +. +.It Fl -enable-source-maps +Enable Source Map v3 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 config +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 config +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-experimental-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 + } +} +.Ed +In the \fBnodeOptions\fR field, only flags that are allowed in \fBNODE_OPTIONS\fR are supported. +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 +.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. +If duplicate keys are present in the configuration file, only +the first key will be used. +The configuration parser will throw an error if the configuration file contains +unknown keys or keys that cannot used in \fBNODE_OPTIONS\fR. +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-loader Ns = Ns Ar module +Specify the \fBmodule\fR containing exported 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-require-module +Supports loading a synchronous ES module graph in \fBrequire()\fR. +See Loading ECMAScript modules using \fBrequire()\fR. +. +.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-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-transform-types +Enables the transformation of TypeScript-only syntax into JavaScript code. +Implies \fB--enable-source-maps\fR. +. +.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-wasm-modules +Enable experimental WebAssembly module support. +. +.It Fl -experimental-webstorage +Enable experimental \fBWeb Storage\fR support. +. +.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-experimental-strip-types\fR. +The default is \fB"commonjs"\fR. +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. This flag is a no-op unless +Node.js is started with the \fB--experimental-webstorage\fR flag. +. +.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 -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 +Disable support for loading a synchronous ES module graph in \fBrequire()\fR. +See Loading ECMAScript modules using \fBrequire()\fR. +. +.It Fl -no-experimental-sqlite +Disable the experimental \fBnode:sqlite\fR module. +. +.It Fl -no-experimental-strip-types +Disable experimental type-stripping for TypeScript files. +For more information, see the TypeScript type-stripping documentation. +. +.It Fl -no-experimental-websocket +Disable exposition of \fBWebSocket\fR on the global scope. +. +.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-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 +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 -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/\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 eport-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. +Only CommonJS modules are supported. +Use \fB--import\fR to preload an ECMAScript 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 -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-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-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-shard +Test suite shard to execute in a format of \fB/\fR, where +\fBindex\fR is a positive integer, index of divided parts +\fBtotal\fR is a positive integer, total of divided part +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-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 planned to follow +Chromium's policy for locally trusted certificates: +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 +Distrust:.Bl -bullet +.It +Any certificate where the “When using this certificate” flag is set to “Never Trust” or +.It +Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Never Trust.” +.El +.El +.El +On Windows, the following settings are respected (unlike Chromium's policy, distrust +and intermediate CA are not currently supported): +.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 certificates +do not forbid them for TLS server authentication before using them. +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. +.Bd -literal +node --watch index.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. +.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 and \fBSlowBuffer\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_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-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-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-transform-types\fR +.It +\fB--experimental-vm-modules\fR +.It +\fB--experimental-wasi-unstable-preview1\fR +.It +\fB--experimental-wasm-modules\fR +.It +\fB--experimental-webstorage\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--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-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-warnings\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--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\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-isolation\fR +.It +\fB--test-name-pattern\fR +.It +\fB--test-only\fR +.It +\fB--test-reporter-destination\fR +.It +\fB--test-reporter\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-largepages\fR +.It +\fB--use-openssl-ca\fR +.It +\fB--use-system-ca\fR +.It +\fB--v8-pool-size\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 currently only affects requests sent over \fBfetch()\fR. Support for other +built-in \fBhttp\fR and \fBhttps\fR methods is under way. +. +.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 +\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 guranteed 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