diff --git a/BUILDING.md b/BUILDING.md index bea9893eb666ea..3dd38762108f86 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -558,7 +558,7 @@ NODE=/path/to/node make doc-only To read the man page: ```bash -man out/doc/node.1 +man doc/node.1 ``` If you prefer to read the full documentation in a browser, run the following. diff --git a/Makefile b/Makefile index 0bd40c5970a7ad..961682e607272c 100644 --- a/Makefile +++ b/Makefile @@ -196,7 +196,7 @@ config.gypi: configure configure.py src/node_version.h fi .PHONY: install -install: all out/doc/node.1 ## Install node into $PREFIX (default=/usr/local). +install: all ## Install node into $PREFIX (default=/usr/local). $(PYTHON) tools/install.py $@ --dest-dir '$(DESTDIR)' --prefix '$(PREFIX)' .PHONY: uninstall @@ -856,7 +856,7 @@ VERSION=v$(RAWVER) .PHONY: doc-only .NOTPARALLEL: doc-only -doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/node.1 out/doc/api/all.html out/doc/api/all.json out/doc/llms.txt out/doc/apilinks.json ## Builds the docs with the local or the global Node.js binary. +doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json out/doc/llms.txt out/doc/apilinks.json ## Builds the docs with the local or the global Node.js binary. .PHONY: doc doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary. @@ -932,19 +932,6 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc ) \ fi -out/doc/node.1: doc/api/cli.md tools/doc/node_modules | out/doc - @if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \ - echo "Skipping $@ (no crypto and/or no ICU)"; \ - else \ - $(call available-node, \ - $(DOC_KIT) generate \ - -t man-page \ - -i $< \ - -o $(@D) \ - -v $(VERSION) \ - ) \ - fi - .PHONY: docopen docopen: doc-only ## Open the documentation in a web browser. @$(PYTHON) -mwebbrowser file://$(abspath $<) @@ -1282,7 +1269,7 @@ $(TARBALL): $(TARBALL_DEPS) git checkout-index -a -f --prefix=$(TARNAME)/ ifneq ($(SKIP_SHARED_DEPS), 1) mkdir -p $(TARNAME)/doc/api - cp out/doc/node.1 $(TARNAME)/doc/node.1 + cp doc/node.1 $(TARNAME)/doc/node.1 cp -r out/doc/api/* $(TARNAME)/doc/api/ endif sed 's/fileset = fileset.intersection (fileset.gitTracked root)/fileset =/' tools/nix/v8.nix > $(TARNAME)/tools/nix/v8.nix diff --git a/doc/node.1 b/doc/node.1 new file mode 100644 index 00000000000000..1bfc09a5934885 --- /dev/null +++ b/doc/node.1 @@ -0,0 +1,2432 @@ +.\" +.\" This file was generated automatically by the @node-core/doc-kit tool. +.\" Please do not edit this file manually. Make any updates to cli.md +.\" and regenerate the file afterward. +.\" +.\" To regenerate this file, run `make doc/node.1`. +.\" +.\"====================================================================== +.Dd $Mdocdate$ +.Dt NODE 1 +. +.Sh NAME +.Nm node +.Nd server-side JavaScript runtime +. +.Sh SYNOPSIS +.Nm node +.Op Ar options +.Op Ar v8 options +.Op Ar | 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 +The \fBchild_process.fork()\fR API inherits the execution arguments from the +parent process. This means that if Node.js is started with the Permission +Model enabled and the \fB--allow-child-process\fR flag is set, any child process +created using \fBchild_process.fork()\fR will automatically receive all relevant +Permission Model flags. +This behavior also applies to \fBchild_process.spawn()\fR, but in that case, the +flags are propagated via the \fBNODE_OPTIONS\fR environment variable rather than +directly through the process arguments. +. +.It Fl -allow-ffi +When using the Permission Model, the process will not be able to use FFI +APIs by default. Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR +exception unless the user explicitly passes the \fB--allow-ffi\fR flag when +starting Node.js. The \fBnode:ffi\fR module also requires the +\fB--experimental-ffi\fR flag and is only available in builds with FFI support. +Example: +.Bd -literal +const { DynamicLibrary } = require('node:ffi'); +const lib = new DynamicLibrary('mylib.so'); +.Ed +.Bd -literal +$ node --permission --experimental-ffi index.js +Error: Access to this API has been restricted. Use --allow-ffi to manage permissions. + at node:internal/main/run_main_module:17:47 { + code: 'ERR_ACCESS_DENIED', + permission: 'FFI' +} +.Ed +. +.It Fl -allow-fs-read +This flag configures file system read permissions using +the Permission Model. +The valid arguments for the \fB--allow-fs-read\fR flag are: +.Bl -bullet +.It +\fB*\fR - To allow all \fBFileSystemRead\fR operations. +.It +Multiple paths can be allowed using multiple \fB--allow-fs-read\fR flags. +Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder1/\fR +.El +Examples can be found in the File System Permissions documentation. +The initializer module and custom \fB--require\fR modules has a implicit +read permission. +.Bd -literal +$ node --permission -r custom-require.js -r custom-require-2.js index.js +.Ed +.Bl -bullet +.It +The \fBcustom-require.js\fR, \fBcustom-require-2.js\fR, and \fBindex.js\fR will be +by default in the allowed read list. +.El +.Bd -literal +process.permission.has('fs.read', 'index.js'); // true +process.permission.has('fs.read', 'custom-require.js'); // true +process.permission.has('fs.read', 'custom-require-2.js'); // true +.Ed +. +.It Fl -allow-fs-write +This flag configures file system write permissions using +the Permission Model. +The valid arguments for the \fB--allow-fs-write\fR flag are: +.Bl -bullet +.It +\fB*\fR - To allow all \fBFileSystemWrite\fR operations. +.It +Multiple paths can be allowed using multiple \fB--allow-fs-write\fR flags. +Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder1/\fR +.El +Paths delimited by comma (\fB,\fR) are no longer allowed. +When passing a single flag with a comma a warning will be displayed. +Examples can be found in the File System Permissions documentation. +. +.It Fl -allow-inspector +When using the Permission Model, the process will not be able to connect +through inspector protocol. +Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the +user explicitly passes the \fB--allow-inspector\fR flag when starting Node.js. +Example: +.Bd -literal +const { Session } = require('node:inspector/promises'); + +const session = new Session(); +session.connect(); +.Ed +.Bd -literal +$ node --permission index.js +Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions. + code: 'ERR_ACCESS_DENIED', +} +.Ed +. +.It Fl -allow-net +When using the Permission Model, the process will not be able to access +network by default. +Attempts to do so will throw an \fBERR_ACCESS_DENIED\fR unless the +user explicitly passes the \fB--allow-net\fR flag when starting Node.js. +Example: +.Bd -literal +const http = require('node:http'); +// Attempt to bypass the permission +const req = http.get('http://example.com', () => {}); + +req.on('error', (err) => { + console.log('err', err); +}); +.Ed +.Bd -literal +$ node --permission index.js +Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions. + code: 'ERR_ACCESS_DENIED', +} +.Ed +. +.It Fl -allow-wasi +When using the Permission Model, the process will not be capable of creating +any WASI instances by default. +For security reasons, the call will throw an \fBERR_ACCESS_DENIED\fR unless the +user explicitly passes the flag \fB--allow-wasi\fR in the main Node.js process. +Example: +.Bd -literal +const { WASI } = require('node:wasi'); +// Attempt to bypass the permission +new WASI({ + version: 'preview1', + // Attempt to mount the whole filesystem + preopens: { + '/': '/', + }, +}); +.Ed +.Bd -literal +$ node --permission --allow-fs-read=* index.js + +Error: Access to this API has been restricted + at node:internal/main/run_main_module:30:49 { + code: 'ERR_ACCESS_DENIED', + permission: 'WASI', +} +.Ed +. +.It Fl -allow-worker +When using the Permission Model, the process will not be able to create any +worker threads by default. +For security reasons, the call will throw an \fBERR_ACCESS_DENIED\fR unless the +user explicitly pass the flag \fB--allow-worker\fR in the main Node.js process. +Example: +.Bd -literal +const { Worker } = require('node:worker_threads'); +// Attempt to bypass the permission +new Worker(__filename); +.Ed +.Bd -literal +$ node --permission --allow-fs-read=* index.js + +Error: Access to this API has been restricted + at node:internal/main/run_main_module:17:47 { + code: 'ERR_ACCESS_DENIED', + permission: 'WorkerThreads' +} +.Ed +. +.It Fl -build-sea Ns = Ns Ar config +Generates a single executable application from a JSON +configuration file. The argument must be a path to the configuration file. If +the path is not absolute, it is resolved relative to the current working +directory. +For configuration fields, cross-platform notes, and asset APIs, see +the single executable application documentation. +. +.It Fl -build-snapshot +Generates a snapshot blob when the process exits and writes it to +disk, which can be loaded later with \fB--snapshot-blob\fR. +When building the snapshot, if \fB--snapshot-blob\fR is not specified, +the generated blob will be written, by default, to \fBsnapshot.blob\fR +in the current working directory. Otherwise it will be written to +the path specified by \fB--snapshot-blob\fR. +.Bd -literal +$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js + +# Run snapshot.js to initialize the application and snapshot the +# state of it into snapshot.blob. +$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js + +$ echo "console.log(globalThis.foo)" > index.js + +# Load the generated snapshot and start the application from index.js. +$ node --snapshot-blob snapshot.blob index.js +I am from the snapshot +.Ed +The \fBv8.startupSnapshot\fR API can be used to specify an entry point at +snapshot building time, thus avoiding the need of an additional entry +script at deserialization time: +.Bd -literal +$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js +$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js +$ node --snapshot-blob snapshot.blob +I am from the snapshot +.Ed +For more information, check out the \fBv8.startupSnapshot\fR API documentation. +The snapshot currently only supports loading a single entrypoint during the +snapshot building process, which can load built-in modules, but not additional user-land modules. +Users can bundle their applications into a single script with their bundler +of choice before building a snapshot. +As it's complicated to ensure the serializablility of all built-in modules, +which are also growing over time, only a subset of the built-in modules are +well tested to be serializable during the snapshot building process. +The Node.js core test suite checks that a few fairly complex applications +can be snapshotted. The list of built-in modules being +captured by the built-in snapshot of Node.js is considered supported. +When the snapshot builder encounters a built-in module that cannot be +serialized, it may crash the snapshot building process. In that case a typical +workaround would be to delay loading that module until +runtime, using either \fBv8.startupSnapshot.setDeserializeMainFunction()\fR or +\fBv8.startupSnapshot.addDeserializeCallback()\fR. If serialization for +an additional module during the snapshot building process is needed, +please file a request in the Node.js issue tracker and link to it in the +tracking issue for user-land snapshots. +. +.It Fl -build-snapshot-config +Specifies the path to a JSON configuration file which configures snapshot +creation behavior. +The following options are currently supported: +.Bl -bullet +.It +\fBbuilder\fR \fB\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 is used as a template +for the file name. The following placeholder is supported and will be +substituted at runtime: +.Bl -bullet +.It +\fB${pid}\fR — the current process ID +.El +.Bd -literal +$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js +$ ls *.cpuprofile +CPU.15293.cpuprofile +.Ed +. +.It Fl -cpu-prof-dir +Specify the directory where the CPU profiles generated by \fB--cpu-prof\fR will +be placed. +The default value is controlled by the +\fB--diagnostic-dir\fR command-line option. +. +.It Fl -cpu-prof-interval +Specify the sampling interval in microseconds for the CPU profiles generated +by \fB--cpu-prof\fR. The default is 1000 microseconds. +. +.It Fl -cpu-prof-name +Specify the file name of the CPU profile generated by \fB--cpu-prof\fR. +. +.It Fl -diagnostic-dir Ns = Ns Ar directory +Set the directory to which all diagnostic output files are written. +Defaults to current working directory. +Affects the default output directory of: +.Bl -bullet +.It +\fB--cpu-prof-dir\fR +.It +\fB--heap-prof-dir\fR +.It +\fB--redirect-warnings\fR +.El +. +.It Fl -disable-proto Ns = Ns Ar mode +Disable the \fBObject.prototype.__proto__\fR property. If \fBmode\fR is \fBdelete\fR, the +property is removed entirely. If \fBmode\fR is \fBthrow\fR, accesses to the +property throw an exception with the code \fBERR_PROTO_ACCESS\fR. +. +.It Fl -disable-sigusr1 +Disable the ability of starting a debugging session by sending a +\fBSIGUSR1\fR signal to the process. +. +.It Fl -disable-warning Ns = Ns Ar code-or-type +Disable specific process warnings by \fBcode\fR or \fBtype\fR. +Warnings emitted from \fBprocess.emitWarning()\fR may contain a +\fBcode\fR and a \fBtype\fR. This option will not-emit warnings that have a matching +\fBcode\fR or \fBtype\fR. +List of deprecation warnings. +The Node.js core warning types are: \fBDeprecationWarning\fR and +\fBExperimentalWarning\fR +For example, the following script will not emit +DEP0025 \fBrequire('node:sys')\fR when executed with +\fBnode --disable-warning=DEP0025\fR: +.Bd -literal +import sys from 'node:sys'; +.Ed +.Bd -literal +const sys = require('node:sys'); +.Ed +For example, the following script will emit the +DEP0025 \fBrequire('node:sys')\fR, but not any Experimental +Warnings (such as +ExperimentalWarning: \fBvm.measureMemory\fR is an experimental feature +in <=v21) when executed with \fBnode --disable-warning=ExperimentalWarning\fR: +.Bd -literal +import sys from 'node:sys'; +import vm from 'node:vm'; + +vm.measureMemory(); +.Ed +.Bd -literal +const sys = require('node:sys'); +const vm = require('node:vm'); + +vm.measureMemory(); +.Ed +. +.It Fl -disable-wasm-trap-handler +Node.js enables V8's trap-handler-based WebAssembly bound checks on 64-bit platforms, +which significantly improves WebAssembly performance by eliminating the need for +inline bound checks. This optimization requires allocating a large virtual memory +cage per WebAssembly memory instance (currently typically 8GB for 32-bit WebAssembly memory, +16GB for 64-bit WebAssembly memory) to trap out-of-bound accesses. On most 64-bit +platforms, the virtual memory address space is usually large enough (around 128TB) +to accommodate typical WebAssembly usages, but if the machine has manual limits +on virtual memory (e.g. through \fBulimit -v\fR), WebAssembly memory allocation is +more likely to fail with \fBWebAssembly.Memory(): could not allocate memory\fR. +At startup, Node.js automatically checks whether there is enough virtual memory +available to allocate at least one cage, and if not, the trap-handler optimization +is automatically disabled so that WebAssembly can still run using inline +bound checks (with less optimal performance). But if the application needs to create +many WebAssembly memory instances and the machine still configures a relatively high +limit on virtual memory, allocation of WebAssembly memory instances may still fail +more quickly than expected due to the raised virtual memory usage. +\fB--disable-wasm-trap-handler\fR fully disables this optimization so that WebAssembly memory +instances always use inline bound checks instead of reserving large virtual memory cages. +This allows more instances to be created when the virtual memory address space available +to the Node.js process is limited. +. +.It Fl -disallow-code-generation-from-strings +Make built-in language features like \fBeval\fR and \fBnew Function\fR that generate +code from strings throw an exception instead. This does not affect the Node.js +\fBnode:vm\fR module. +. +.It Fl -dns-result-order Ns = Ns Ar order +Set the default value of \fBorder\fR in \fBdns.lookup()\fR and +\fBdnsPromises.lookup()\fR. The value could be: +.Bl -bullet +.It +\fBipv4first\fR: sets default \fBorder\fR to \fBipv4first\fR. +.It +\fBipv6first\fR: sets default \fBorder\fR to \fBipv6first\fR. +.It +\fBverbatim\fR: sets default \fBorder\fR to \fBverbatim\fR. +.El +The default is \fBverbatim\fR and \fBdns.setDefaultResultOrder()\fR have higher +priority than \fB--dns-result-order\fR. +. +.It Fl -enable-fips +Enable FIPS-compliant crypto at startup. (Requires Node.js to be built +against FIPS-compatible OpenSSL.) +. +.It Fl -enable-source-maps +Enable Source Map support for stack traces. +When using a transpiler, such as TypeScript, stack traces thrown by an +application reference the transpiled code, not the original source position. +\fB--enable-source-maps\fR enables caching of Source Maps and makes a best +effort to report stack traces relative to the original source file. +Overriding \fBError.prepareStackTrace\fR may prevent \fB--enable-source-maps\fR from +modifying the stack trace. Call and return the results of the original +\fBError.prepareStackTrace\fR in the overriding function to modify the stack trace +with source maps. +.Bd -literal +const originalPrepareStackTrace = Error.prepareStackTrace; +Error.prepareStackTrace = (error, trace) => { + // Modify error and trace and format stack trace with + // original Error.prepareStackTrace. + return originalPrepareStackTrace(error, trace); +}; +.Ed +Note, enabling source maps can introduce latency to your application +when \fBError.stack\fR is accessed. If you access \fBError.stack\fR frequently +in your application, take into account the performance implications +of \fB--enable-source-maps\fR. +. +.It Fl -entry-url +When present, Node.js will interpret the entry point as a URL, rather than a +path. +Follows ECMAScript module resolution rules. +Any query parameter or hash in the URL will be accessible via \fBimport.meta.url\fR. +.Bd -literal +node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too' +node --entry-url 'file.ts?query#hash' +node --entry-url 'data:text/javascript,console.log("Hello")' +.Ed +. +.It Fl -env-file-if-exists Ns = Ns Ar file +Behavior is the same as \fB--env-file\fR, but an error is not thrown if the file +does not exist. +. +.It Fl -env-file Ns = Ns Ar file +Loads environment variables from a file relative to the current directory, +making them available to applications on \fBprocess.env\fR. The environment +variables which configure Node.js, such as \fBNODE_OPTIONS\fR, +are parsed and applied. If the same variable is defined in the environment and +in the file, the value from the environment takes precedence. +You can pass multiple \fB--env-file\fR arguments. Subsequent files override +pre-existing variables defined in previous files. +An error is thrown if the file does not exist. +.Bd -literal +node --env-file=.env --env-file=.development.env index.js +.Ed +The format of the file should be one line per key-value pair of environment +variable name and value separated by \fB=\fR: +.Bd -literal +PORT=3000 +.Ed +Any text after a \fB#\fR is treated as a comment: +.Bd -literal +# This is a comment +PORT=3000 # This is also a comment +.Ed +Values can start and end with the following quotes: \fB`\fR, \fB"\fR or \fB'\fR. +They are omitted from the values. +.Bd -literal +USERNAME="nodejs" # will result in `nodejs` as the value. +.Ed +Multi-line values are supported: +.Bd -literal +MULTI_LINE="THIS IS +A MULTILINE" +# will result in `THIS IS\\nA MULTILINE` as the value. +.Ed +Export keyword before a key is ignored: +.Bd -literal +export USERNAME="nodejs" # will result in `nodejs` as the value. +.Ed +If you want to load environment variables from a file that may not exist, you +can use the \fB--env-file-if-exists\fR flag instead. +. +.It Fl e , Fl -eval Ar "script" +Evaluate the following argument as JavaScript. The modules which are +predefined in the REPL can also be used in \fBscript\fR. +If \fBscript\fR starts with \fB-\fR, pass it using \fB=\fR (for example, +\fBnode --print --eval=-42\fR) so it is parsed as the value of \fB--eval\fR. +On Windows, using \fBcmd.exe\fR a single quote will not work correctly because it +only recognizes double \fB"\fR for quoting. In Powershell or Git bash, both \fB'\fR +and \fB"\fR are usable. +It is possible to run code containing inline types unless the +\fB--no-strip-types\fR flag is provided. +. +.It Fl -experimental-addon-modules +Enable experimental import support for \fB.node\fR addons. +. +.It Fl -experimental-config-file Ns = Ns Ar path , Fl -experimental-config-file +If present, Node.js will look for a configuration file at the specified path. +If the path is not specified, Node.js will look for a \fBnode.config.json\fR file +in the current working directory. +To specify a custom path, use the \fB--experimental-config-file=path\fR form. +The space-separated \fB--experimental-config-file path\fR form is not supported. +The alias \fB--experimental-default-config-file\fR is equivalent to +\fB--experimental-config-file\fR without an argument. +Node.js will read the configuration file and apply the settings. The +configuration file should be a JSON file with the following structure. \fBvX.Y.Z\fR +in the \fB$schema\fR must be replaced with the version of Node.js you are using or +\fBlatest-vX.x\fR for the latest version of that major release line. +.Bd -literal +{ + "$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json", + "nodeOptions": { + "import": [ + "amaro/strip" + ], + "watch-path": "src", + "watch-preserve-output": true + }, + "test": { + "test-isolation": "process" + }, + "watch": { + "watch-preserve-output": true + } +} +.Ed +The configuration file supports namespace-specific options: +.Bl -bullet +.It +The \fBnodeOptions\fR field contains CLI flags that are allowed in \fBNODE_OPTIONS\fR. +.It +Namespace fields like \fBtest\fR, \fBwatch\fR, and \fBpermission\fR contain configuration specific to that subsystem. +.El +The configuration file can target a specific Node.js major version with +\fBnodeVersion\fR: +.Bd -literal +{ + "nodeVersion": 25, + "nodeOptions": { + "watch-path": "src" + } +} +.Ed +To keep multiple version-specific configurations in the same file, use the +\fBconfigs\fR array. Node.js will use the first entry whose \fBnodeVersion\fR matches +the current Node.js major version: +.Bd -literal +{ + "$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json", + "configs": [ + { + "nodeVersion": 25, + "config": { + "$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json", + "nodeOptions": { + "watch-path": "src" + } + } + } + ] +} +.Ed +When \fBconfigs\fR is used, the top level may only contain \fB$schema\fR and +\fBconfigs\fR. Each \fBconfigs\fR item must define an integer \fBnodeVersion\fR and an +object \fBconfig\fR. A single top-level config does not require \fBnodeVersion\fR, but +if present it must match the current Node.js major version. +When a namespace is present in the +configuration file, Node.js automatically enables the corresponding flag +(e.g., \fB--test\fR, \fB--watch\fR, \fB--permission\fR). This allows you to configure +subsystem-specific options without explicitly passing the flag on the command line. +For example: +.Bd -literal +{ + "test": { + "test-isolation": "process" + } +} +.Ed +is equivalent to: +.Bd -literal +node --test --test-isolation=process +.Ed +To disable the automatic flag while still using namespace options, you can +explicitly set the flag to \fBfalse\fR within the namespace: +.Bd -literal +{ + "test": { + "test": false, + "test-isolation": "process" + } +} +.Ed +No-op flags are not supported. +Not all V8 flags are currently supported. +It is possible to use the official JSON schema +to validate the configuration file, which may vary depending on the Node.js version. +Each key in the configuration file corresponds to a flag that can be passed +as a command-line argument. The value of the key is the value that would be +passed to the flag. +For example, the configuration file above is equivalent to +the following command-line arguments: +.Bd -literal +node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process +.Ed +The priority in configuration is as follows: +.Bl -bullet +.It +NODE_OPTIONS and command-line options +.It +Dotenv NODE_OPTIONS +.It +Configuration file +.El +Values in the configuration file will not override the values in the environment +variables, command-line options, or the \fBNODE_OPTIONS\fR env file parsed by the +\fB--env-file\fR flag. +Keys cannot be duplicated within the same or different namespaces. +The configuration parser will throw an error if the configuration file contains +unknown keys or keys that cannot be used in a namespace. +Node.js will not sanitize or perform validation on the user-provided configuration, +so \fBNEVER\fR use untrusted configuration files. +. +.It Fl -experimental-default-config-file +This flag is an alias for \fB--experimental-config-file\fR without an argument. +If present, Node.js will look for a +\fBnode.config.json\fR file in the current working directory and load it as a +configuration file. +. +.It Fl -experimental-dtls +Enable experimental support for the DTLS protocol. See the +dtls documentation for details. +. +.It Fl -experimental-eventsource +Enable exposition of EventSource Web API on the global scope. +. +.It Fl -experimental-ffi +Enable the experimental \fBnode:ffi\fR module. +This flag is only available in builds with FFI support. +. +.It Fl -experimental-import-meta-resolve +Enable experimental \fBimport.meta.resolve()\fR parent URL support, which allows +passing a second \fBparentURL\fR argument for contextual resolution. +Previously gated the entire \fBimport.meta.resolve\fR feature. +. +.It Fl -experimental-inspector-network-resource +Enable experimental support for inspector network resources. +. +.It Fl -experimental-loader Ns = Ns Ar module +Specify the \fBmodule\fR containing exported asynchronous module customization hooks. +\fBmodule\fR may be any string accepted as an \fBimport\fR specifier. +This feature requires \fB--allow-worker\fR if used with the Permission Model. +. +.It Fl -experimental-network-inspection +Enable experimental support for the network inspection with Chrome DevTools. +. +.It Fl -experimental-package-map Ns = Ns Ar +Enable experimental package map resolution. The \fBpath\fR argument specifies the +location of a JSON configuration file that defines package resolution mappings. +.Bd -literal +node --experimental-package-map=./package-map.json app.js +.Ed +When enabled, bare specifier resolution consults the package map for resolution. +This allows explicit control over which packages can import which dependencies. +See Package maps for details on the configuration file format and +resolution algorithm. +. +.It Fl -experimental-print-required-tla +If the ES module being \fBrequire()\fR'd contains top-level \fBawait\fR, this flag +allows Node.js to evaluate the module, try to locate the +top-level awaits, and print their location to help users find them. +. +.It Fl -experimental-quic +Enable experimental support for the QUIC protocol. +. +.It Fl -experimental-sea-config +Use this flag to generate a blob that can be injected into the Node.js +binary to produce a single executable application. See the documentation +about this configuration for details. +. +.It Fl -experimental-shadow-realm +Use this flag to enable ShadowRealm support. +. +.It Fl -experimental-storage-inspection +Enable experimental support for storage inspection +. +.It Fl -experimental-stream-iter +Enable the experimental \fBnode:stream/iter\fR module. +. +.It Fl -experimental-test-coverage +When used in conjunction with the \fBnode:test\fR module, a code coverage report is +generated as part of the test runner output. If no tests are run, a coverage +report is not generated. See the documentation on +collecting code coverage from tests for more details. +. +.It Fl -experimental-test-module-mocks +Enable module mocking in the test runner. +This feature requires \fB--allow-worker\fR if used with the Permission Model. +. +.It Fl -experimental-test-tag-filter Ns = Ns Ar +Run only tests whose tag set contains \fB\fR. Tests declare tags via the +\fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or \fBdescribe()\fR; tags +inherit from suites to nested tests by union. Filtering is +case-insensitive. +The flag may be specified more than once; tests must contain \fBevery\fR +filter value to run. See Test tags for details on declaring and +inheriting tags. +. +.It Fl -experimental-vfs +Enable the experimental \fBnode:vfs\fR module. +. +.It Fl -experimental-vm-modules +Enable experimental ES Module support in the \fBnode:vm\fR module. +. +.It Fl -experimental-wasi-unstable-preview1 +Enable experimental WebAssembly System Interface (WASI) support. +. +.It Fl -experimental-worker-inspection +Enable experimental support for the worker inspection with Chrome DevTools. +. +.It Fl -expose-gc +This flag will expose the gc extension from V8. +.Bd -literal +if (globalThis.gc) { + globalThis.gc(); +} +.Ed +. +.It Fl -force-context-aware +Disable loading native addons that are not context-aware. +. +.It Fl -force-fips +Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.) +(Same requirements as \fB--enable-fips\fR.) +. +.It Fl -force-node-api-uncaught-exceptions-policy +Enforces \fBuncaughtException\fR event on Node-API asynchronous callbacks. +To prevent from an existing add-on from crashing the process, this flag is not +enabled by default. In the future, this flag will be enabled by default to +enforce the correct behavior. +. +.It Fl -frozen-intrinsics +Enable experimental frozen intrinsics like \fBArray\fR and \fBObject\fR. +Only the root context is supported. There is no guarantee that +\fBglobalThis.Array\fR is indeed the default intrinsic reference. Code may break +under this flag. +To allow polyfills to be added, +\fB--require\fR and \fB--import\fR both run before freezing intrinsics. +. +.It Fl -heap-prof +Starts the V8 heap profiler on start up, and writes the heap profile to disk +before exit. +If \fB--heap-prof-dir\fR is not specified, the generated profile is placed +in the current working directory. +If \fB--heap-prof-name\fR is not specified, the generated profile is +named \fBHeap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile\fR. +.Bd -literal +$ node --heap-prof index.js +$ ls *.heapprofile +Heap.20190409.202950.15293.0.001.heapprofile +.Ed +. +.It Fl -heap-prof-dir +Specify the directory where the heap profiles generated by \fB--heap-prof\fR will +be placed. +The default value is controlled by the +\fB--diagnostic-dir\fR command-line option. +. +.It Fl -heap-prof-interval +Specify the average sampling interval in bytes for the heap profiles generated +by \fB--heap-prof\fR. The default is 512 * 1024 bytes. +. +.It Fl -heap-prof-name +Specify the file name of the heap profile generated by \fB--heap-prof\fR. +. +.It Fl -heapsnapshot-near-heap-limit Ns = Ns Ar max_count +Writes a V8 heap snapshot to disk when the V8 heap usage is approaching the +heap limit. \fBcount\fR should be a non-negative integer (in which case +Node.js will write no more than \fBmax_count\fR snapshots to disk). +When generating snapshots, garbage collection may be triggered and bring +the heap usage down. Therefore multiple snapshots may be written to disk +before the Node.js instance finally runs out of memory. These heap snapshots +can be compared to determine what objects are being allocated during the +time consecutive snapshots are taken. It's not guaranteed that Node.js will +write exactly \fBmax_count\fR snapshots to disk, but it will try +its best to generate at least one and up to \fBmax_count\fR snapshots before the +Node.js instance runs out of memory when \fBmax_count\fR is greater than \fB0\fR. +Generating V8 snapshots takes time and memory (both memory managed by the +V8 heap and native memory outside the V8 heap). The bigger the heap is, +the more resources it needs. Node.js will adjust the V8 heap to accommodate +the additional V8 heap memory overhead, and try its best to avoid using up +all the memory available to the process. When the process uses +more memory than the system deems appropriate, the process may be terminated +abruptly by the system, depending on the system configuration. +.Bd -literal +$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js +Wrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot +Wrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot +Wrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot + +<--- Last few GCs ---> + +[49580:0x110000000] 4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed +[49580:0x110000000] 4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed + + +<--- JS stacktrace ---> + +FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory +.... +.Ed +. +.It Fl -heapsnapshot-signal Ns = Ns Ar signal +Enables a signal handler that causes the Node.js process to write a heap dump +when the specified signal is received. \fBsignal\fR must be a valid signal name. +Disabled by default. +.Bd -literal +$ node --heapsnapshot-signal=SIGUSR2 index.js & +$ ps aux +USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND +node 1 5.5 6.1 787252 247004 ? Ssl 16:43 0:02 node --heapsnapshot-signal=SIGUSR2 index.js +$ kill -USR2 1 +$ ls +Heap.20190718.133405.15554.0.001.heapsnapshot +.Ed +. +.It Fl h , Fl -help +Print node command-line options. +The output of this option is less detailed than this document. +. +.It Fl -icu-data-dir Ns = Ns Ar file +Specify ICU data load path. (Overrides \fBNODE_ICU_DATA\fR.) +. +.It Fl -import Ns = Ns Ar module +Preload the specified module at startup. If the flag is provided several times, +each module will be executed sequentially in the order they appear, starting +with the ones provided in \fBNODE_OPTIONS\fR. +Follows ECMAScript module resolution rules. +Use \fB--require\fR to load a CommonJS module. +Modules preloaded with \fB--require\fR will run before modules preloaded with \fB--import\fR. +Modules are preloaded into the main thread as well as any worker threads, +forked processes, or clustered processes. +. +.It Fl -input-type Ns = Ns Ar type +This configures Node.js to interpret \fB--eval\fR or \fBSTDIN\fR input as CommonJS or +as an ES module. Valid values are \fB"commonjs"\fR, \fB"module"\fR, \fB"module-typescript"\fR and \fB"commonjs-typescript"\fR. +The \fB"-typescript"\fR values are not available with the flag \fB--no-strip-types\fR. +The default is no value, or \fB"commonjs"\fR if \fB--no-experimental-detect-module\fR is passed. +If \fB--input-type\fR is not provided, +Node.js will try to detect the syntax with the following steps: +.Bl -bullet +.It +Run the input as CommonJS. +.It +If step 1 fails, run the input as an ES module. +.It +If step 2 fails with a SyntaxError, strip the types. +.It +If step 3 fails with an error code \fBERR_UNSUPPORTED_TYPESCRIPT_SYNTAX\fR +or \fBERR_INVALID_TYPESCRIPT_SYNTAX\fR, +throw the error from step 2, including the TypeScript error in the message, +else run as CommonJS. +.It +If step 4 fails, run the input as an ES module. +.El +To avoid the delay of multiple syntax detection passes, the \fB--input-type=type\fR flag can be used to specify +how the \fB--eval\fR input should be interpreted. +The REPL does not support this option. Usage of \fB--input-type=module\fR with +\fB--print\fR will throw an error, as \fB--print\fR does not support ES module +syntax. +. +.It Fl -insecure-http-parser +Enable leniency flags on the HTTP parser. This may allow +interoperability with non-conformant HTTP implementations. +When enabled, the parser will accept the following: +.Bl -bullet +.It +Invalid HTTP headers values. +.It +Invalid HTTP versions. +.It +Allow message containing both \fBTransfer-Encoding\fR +and \fBContent-Length\fR headers. +.It +Allow extra data after message when \fBConnection: close\fR is present. +.It +Allow extra transfer encodings after \fBchunked\fR has been provided. +.It +Allow \fB\\n\fR to be used as token separator instead of \fB\\r\\n\fR. +.It +Allow \fB\\r\\n\fR not to be provided after a chunk. +.It +Allow spaces to be present after a chunk size and before \fB\\r\\n\fR. +.El +All the above will expose your application to request smuggling +or poisoning attack. Avoid using this option. +. +.It Fl -inspect-brk Ns = Ns Ar [[host:]port] +Activate inspector on \fBhost:port\fR and break at start of user script. +Default \fBhost:port\fR is \fB127.0.0.1:9229\fR. If port \fB0\fR is specified, +a random available port will be used. +See V8 Inspector integration for Node.js for further explanation on Node.js debugger. +See the security warning below regarding the \fBhost\fR +parameter usage. +. +.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. +See the security warning below regarding the \fBhost\fR +parameter usage. +. +.It Fl -inspect Ns = Ns Ar [[host:]port] +Activate inspector on \fBhost:port\fR. Default is \fB127.0.0.1:9229\fR. If port \fB0\fR is +specified, a random available port will be used. +V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug +and profile Node.js instances. The tools attach to Node.js instances via a +tcp port and communicate using the Chrome DevTools Protocol. +See V8 Inspector integration for Node.js for further explanation on Node.js debugger. +. +.It Fl i , Fl -interactive +Opens the REPL even if stdin does not appear to be a terminal. +. +.It Fl -jitless +Disable runtime allocation of executable memory. This may be +required on some platforms for security reasons. It can also reduce attack +surface on other platforms, but the performance impact may be severe. +. +.It Fl -localstorage-file Ns = Ns Ar file +The file used to store \fBlocalStorage\fR data. If the file does not exist, it is +created the first time \fBlocalStorage\fR is accessed. The same file may be shared +between multiple Node.js processes concurrently. +. +.It Fl -max-http-header-size Ns = Ns Ar size +Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB. +. +.It Fl -max-old-space-size-percentage Ns = Ns Ar percentage +Sets the maximum memory size of V8's old memory section as a percentage of available system memory. +This flag takes precedence over \fB--max-old-space-size\fR when both are specified. +The \fBpercentage\fR parameter must be a number greater than 0 and up to 100, representing the percentage +of available system memory to allocate to the V8 heap. +\fBNote:\fR This flag utilizes \fB--max-old-space-size\fR, which may be unreliable on 32-bit platforms due to +integer overflow issues. +.Bd -literal +# Using 50% of available system memory +node --max-old-space-size-percentage=50 index.js + +# Using 75% of available system memory +node --max-old-space-size-percentage=75 index.js +.Ed +. +.It Fl -napi-modules +This option is a no-op. It is kept for compatibility. +. +.It Fl -network-family-autoselection-attempt-timeout +Sets the default value for the network family autoselection attempt timeout. +For more information, see \fBnet.getDefaultAutoSelectFamilyAttemptTimeout()\fR. +. +.It Fl -no-addons +Disable the \fBnode-addons\fR exports condition as well as disable loading +native addons. When \fB--no-addons\fR is specified, calling \fBprocess.dlopen\fR or +requiring a native C++ addon will fail and throw an exception. +. +.It Fl -no-async-context-frame +Disables the use of \fBAsyncLocalStorage\fR backed by \fBAsyncContextFrame\fR and +uses the prior implementation which relied on async_hooks. The previous model +is retained for compatibility with Electron and for cases where the context +flow may differ. However, if a difference in flow is found please report it. +. +.It Fl -no-deprecation +Silence deprecation warnings. +. +.It Fl -no-experimental-detect-module +Disable using syntax detection to determine module type. +. +.It Fl -no-experimental-global-navigator +Disable exposition of Navigator API on the global scope. +. +.It Fl -no-experimental-repl-await +Use this flag to disable top-level await in REPL. +. +.It Fl -no-experimental-require-module +Legacy alias for \fB--no-require-module\fR. +. +.It Fl -no-experimental-sqlite +Disable the experimental \fBnode:sqlite\fR module. +. +.It Fl -no-experimental-websocket +Disable exposition of \fB\fR on the global scope. +. +.It Fl -no-experimental-webstorage +Disable \fBWeb Storage\fR support. +. +.It Fl -no-extra-info-on-fatal-exception +Hide extra information on fatal exception that causes exit. +. +.It Fl -no-force-async-hooks-checks +Disables runtime checks for \fBasync_hooks\fR. These will still be enabled +dynamically when \fBasync_hooks\fR is enabled. +. +.It Fl -no-global-search-paths +Do not search modules from global paths like \fB$HOME/.node_modules\fR and +\fB$NODE_PATH\fR. +. +.It Fl -no-network-family-autoselection +Disables the family autoselection algorithm unless connection options explicitly +enables it. +. +.It Fl -no-require-module +Disable support for loading a synchronous ES module graph in \fBrequire()\fR. +See Loading ECMAScript modules using \fBrequire()\fR. +. +.It Fl -no-strip-types +Disable type-stripping for TypeScript files. +For more information, see the TypeScript type-stripping documentation. +. +.It Fl -no-warnings +Silence all process warnings (including deprecations). +. +.It Fl -node-memory-debug +Enable extra debug checks for memory leaks in Node.js internals. This is +usually only useful for developers debugging Node.js itself. +. +.It Fl -openssl-config Ns = Ns Ar file +Load an OpenSSL configuration file on startup. Among other uses, this can be +used to enable FIPS-compliant crypto if Node.js is built +against FIPS-enabled OpenSSL. +. +.It Fl -openssl-legacy-provider +Enable OpenSSL 3.0 legacy provider. For more information please see +OSSL_PROVIDER-legacy. +. +.It Fl -openssl-shared-config +Enable OpenSSL default configuration section, \fBopenssl_conf\fR to be read from +the OpenSSL configuration file. The default configuration file is named +\fBopenssl.cnf\fR but this can be changed using the environment variable +\fBOPENSSL_CONF\fR, or by using the command line option \fB--openssl-config\fR. +The location of the default OpenSSL configuration file depends on how OpenSSL +is being linked to Node.js. Sharing the OpenSSL configuration may have unwanted +implications and it is recommended to use a configuration section specific to +Node.js which is \fBnodejs_conf\fR and is default when this option is not used. +. +.It Fl -pending-deprecation +Emit pending deprecation warnings. +Pending deprecations are generally identical to a runtime deprecation with the +notable exception that they are turned \fIoff\fR by default and will not be emitted +unless either the \fB--pending-deprecation\fR command-line flag, or the +\fBNODE_PENDING_DEPRECATION=1\fR environment variable, is set. Pending deprecations +are used to provide a kind of selective "early warning" mechanism that +developers may leverage to detect deprecated API usage. +. +.It Fl -permission +Enable the Permission Model for current process. When enabled, the +following permissions are restricted: +.Bl -bullet +.It +File System - manageable through +\fB--allow-fs-read\fR, \fB--allow-fs-write\fR flags +.It +Network - manageable through \fB--allow-net\fR flag +.It +Child Process - manageable through \fB--allow-child-process\fR flag +.It +Worker Threads - manageable through \fB--allow-worker\fR flag +.It +WASI - manageable through \fB--allow-wasi\fR flag +.It +Addons - manageable through \fB--allow-addons\fR flag +.It +FFI - manageable through \fB--allow-ffi\fR flag +.El +. +.It Fl -permission-audit +Enable audit only for the permission model. When enabled, permission checks +are performed but access is not denied. Instead, a warning is emitted for +each permission violation via diagnostics channel. +. +.It Fl -preserve-symlinks +Instructs the module loader to preserve symbolic links when resolving and +caching modules. +By default, when Node.js loads a module from a path that is symbolically linked +to a different on-disk location, Node.js will dereference the link and use the +actual on-disk "real path" of the module as both an identifier and as a root +path to locate other dependency modules. In most cases, this default behavior +is acceptable. However, when using symbolically linked peer dependencies, as +illustrated in the example below, the default behavior causes an exception to +be thrown if \fBmoduleA\fR attempts to require \fBmoduleB\fR as a peer dependency: +.Bd -literal +{appDir} + ├── app + │ ├── index.js + │ └── node_modules + │ ├── moduleA -> {appDir}/moduleA + │ └── moduleB + │ ├── index.js + │ └── package.json + └── moduleA + ├── index.js + └── package.json +.Ed +The \fB--preserve-symlinks\fR command-line flag instructs Node.js to use the +symlink path for modules as opposed to the real path, allowing symbolically +linked peer dependencies to be found. +Note, however, that using \fB--preserve-symlinks\fR can have other side effects. +Specifically, symbolically linked \fInative\fR modules can fail to load if those +are linked from more than one location in the dependency tree (Node.js would +see those as two separate modules and would attempt to load the module multiple +times, causing an exception to be thrown). +The \fB--preserve-symlinks\fR flag does not apply to the main module, which allows +\fBnode --preserve-symlinks node_module/.bin/\fR to work. To apply the same +behavior for the main module, also use \fB--preserve-symlinks-main\fR. +. +.It Fl -preserve-symlinks-main +Instructs the module loader to preserve symbolic links when resolving and +caching the main module (\fBrequire.main\fR). +This flag exists so that the main module can be opted-in to the same behavior +that \fB--preserve-symlinks\fR gives to all other imports; they are separate flags, +however, for backward compatibility with older Node.js versions. +\fB--preserve-symlinks-main\fR does not imply \fB--preserve-symlinks\fR; use +\fB--preserve-symlinks-main\fR in addition to +\fB--preserve-symlinks\fR when it is not desirable to follow symlinks before +resolving relative paths. +See \fB--preserve-symlinks\fR for more information. +. +.It Fl p , Fl -print Ar "script" +Identical to \fB-e\fR but prints the result. +. +.It Fl -prof +Generate V8 profiler output. +. +.It Fl -prof-process +Process V8 profiler output generated using the V8 option \fB--prof\fR. +. +.It Fl -redirect-warnings Ns = Ns Ar file +Write process warnings to the given file instead of printing to stderr. The +file will be created if it does not exist, and will be appended to if it does. +If an error occurs while attempting to write the warning to the file, the +warning will be written to stderr instead. +The \fBfile\fR name may be an absolute path. If it is not, the default directory it +will be written to is controlled by the +\fB--diagnostic-dir\fR command-line option. +. +.It Fl -report-compact +Write reports in a compact format, single-line JSON, more easily consumable +by log processing systems than the default multi-line format designed for +human consumption. +. +.It Fl -report-dir Ns = Ns Ar directory , Fl -report-directory Ns = Ns Ar directory +Location at which the report will be generated. +. +.It Fl -report-exclude-env +When \fB--report-exclude-env\fR is passed the diagnostic report generated will not +contain the \fBenvironmentVariables\fR data. +. +.It Fl -report-exclude-network +Exclude \fBheader.networkInterfaces\fR from the diagnostic report. By default +this is not set and the network interfaces are included. +. +.It Fl -report-filename Ns = Ns Ar filename +Name of the file to which the report will be written. +If the filename is set to \fB'stdout'\fR or \fB'stderr'\fR, the report is written to +the stdout or stderr of the process respectively. +. +.It Fl -report-on-fatalerror +Enables the report to be triggered on fatal errors (internal errors within +the Node.js runtime such as out of memory) that lead to termination of the +application. Useful to inspect various diagnostic data elements such as heap, +stack, event loop state, resource consumption etc. to reason about the fatal +error. +. +.It Fl -report-on-signal +Enables report to be generated upon receiving the specified (or predefined) +signal to the running Node.js process. The signal to trigger the report is +specified through \fB--report-signal\fR. +. +.It Fl -report-signal Ns = Ns Ar signal +Sets or resets the signal for report generation (not supported on Windows). +Default signal is \fBSIGUSR2\fR. +. +.It Fl -report-uncaught-exception +Enables report to be generated when the process exits due to an uncaught +exception. Useful when inspecting the JavaScript stack in conjunction with +native stack and other runtime environment data. +. +.It Fl r , Fl -require Ar module +Preload the specified module at startup. +Follows \fBrequire()\fR's module resolution +rules. \fBmodule\fR may be either a path to a file, or a node module name. +Modules preloaded with \fB--require\fR will run before modules preloaded with \fB--import\fR. +Modules are preloaded into the main thread as well as any worker threads, +forked processes, or clustered processes. +. +.It Fl -run +This runs a specified command from a package.json's \fB"scripts"\fR object. +If a missing \fB"command"\fR is provided, it will list the available scripts. +\fB--run\fR will traverse up to the root directory and finds a \fBpackage.json\fR +file to run the command from. +\fB--run\fR prepends \fB./node_modules/.bin\fR for each ancestor of +the current directory, to the \fBPATH\fR in order to execute the binaries from +different folders where multiple \fBnode_modules\fR directories are present, if +\fBancestor-folder/node_modules/.bin\fR is a directory. +\fB--run\fR executes the command in the directory containing the related \fBpackage.json\fR. +For example, the following command will run the \fBtest\fR script of +the \fBpackage.json\fR in the current folder: +.Bd -literal +$ node --run test +.Ed +You can also pass arguments to the command. Any argument after \fB--\fR will +be appended to the script: +.Bd -literal +$ node --run test -- --verbose +.Ed +. +.It Fl -secure-heap-min Ns = Ns Ar n +When using \fB--secure-heap\fR, the \fB--secure-heap-min\fR flag specifies the +minimum allocation from the secure heap. The minimum value is \fB2\fR. +The maximum value is the lesser of \fB--secure-heap\fR or \fB2147483647\fR. +The value given must be a power of two. +. +.It Fl -secure-heap Ns = Ns Ar n +Initializes an OpenSSL secure heap of \fBn\fR bytes. When initialized, the +secure heap is used for selected types of allocations within OpenSSL +during key generation and other operations. This is useful, for instance, +to prevent sensitive information from leaking due to pointer overruns +or underruns. +The secure heap is a fixed size and cannot be resized at runtime so, +if used, it is important to select a large enough heap to cover all +application uses. +The heap size given must be a power of two. Any value less than 2 +will disable the secure heap. +The secure heap is disabled by default. +The secure heap is not available on Windows. +See \fBCRYPTO_secure_malloc_init\fR for more details. +. +.It Fl -snapshot-blob Ns = Ns Ar path +When used with \fB--build-snapshot\fR, \fB--snapshot-blob\fR specifies the path +where the generated snapshot blob is written to. If not specified, the +generated blob is written to \fBsnapshot.blob\fR in the current working directory. +When used without \fB--build-snapshot\fR, \fB--snapshot-blob\fR specifies the +path to the blob that is used to restore the application state. +When loading a snapshot, Node.js checks that: +.Bl -bullet +.It +The version, architecture, and platform of the running Node.js binary +are exactly the same as that of the binary that generates the snapshot. +.It +The V8 flags and CPU features are compatible with that of the binary +that generates the snapshot. +.El +If they don't match, Node.js refuses to load the snapshot and exits with +status code 1. +. +.It Fl -test +Starts the Node.js command line test runner. This flag cannot be combined with +\fB--watch-path\fR, \fB--check\fR, \fB--eval\fR, \fB--interactive\fR, or the inspector. +See the documentation on running tests from the command line +for more details. +. +.It Fl -test-concurrency +The maximum number of test files that the test runner CLI will execute +concurrently. If \fB--test-isolation\fR is set to \fB'none'\fR, this flag is ignored and +concurrency is one. Otherwise, concurrency defaults to +\fBos.availableParallelism() - 1\fR. +. +.It Fl -test-coverage-branches Ns = Ns Ar threshold +Require a minimum percent of covered branches. If code coverage does not reach +the threshold specified, the process will exit with code \fB1\fR. +. +.It Fl -test-coverage-exclude +Excludes specific files from code coverage using a glob pattern, which can match +both absolute and relative file paths. +This option may be specified multiple times to exclude multiple glob patterns. +If both \fB--test-coverage-exclude\fR and \fB--test-coverage-include\fR are provided, +files must meet \fBboth\fR criteria to be included in the coverage report. +By default all the matching test files are excluded from the coverage report. +Specifying this option will override the default behavior. +. +.It Fl -test-coverage-functions Ns = Ns Ar threshold +Require a minimum percent of covered functions. If code coverage does not reach +the threshold specified, the process will exit with code \fB1\fR. +. +.It Fl -test-coverage-include +Includes specific files in code coverage using a glob pattern, which can match +both absolute and relative file paths. +This option may be specified multiple times to include multiple glob patterns. +If both \fB--test-coverage-exclude\fR and \fB--test-coverage-include\fR are provided, +files must meet \fBboth\fR criteria to be included in the coverage report. +. +.It Fl -test-coverage-lines Ns = Ns Ar threshold +Require a minimum percent of covered lines. If code coverage does not reach +the threshold specified, the process will exit with code \fB1\fR. +. +.It Fl -test-force-exit +Configures the test runner to exit the process once all known tests have +finished executing even if the event loop would otherwise remain active. +. +.It Fl -test-global-setup Ns = Ns Ar module +Specify a module that will be evaluated before all tests are executed and +can be used to setup global state or fixtures for tests. +See the documentation on global setup and teardown for more details. +. +.It Fl -test-isolation Ns = Ns Ar mode +Configures the type of test isolation used in the test runner. When \fBmode\fR is +\fB'process'\fR, each test file is run in a separate child process. When \fBmode\fR is +\fB'none'\fR, all test files run in the same process as the test runner. The default +isolation mode is \fB'process'\fR. This flag is ignored if the \fB--test\fR flag is not +present. See the test runner execution model section for more information. +. +.It Fl -test-name-pattern +A regular expression that configures the test runner to only execute tests +whose name matches the provided pattern. See the documentation on +filtering tests by name for more details. +If both \fB--test-name-pattern\fR and \fB--test-skip-pattern\fR are supplied, +tests must satisfy \fBboth\fR requirements in order to be executed. +. +.It Fl -test-only +Configures the test runner to only execute top level tests that have the \fBonly\fR +option set. This flag is not necessary when test isolation is disabled. +. +.It Fl -test-random-seed +Set the seed used to randomize test execution order. This applies to both test +file execution order and queued tests within each file. Providing this flag +enables randomization implicitly, even without \fB--test-randomize\fR. +The value must be an integer between \fB0\fR and \fB4294967295\fR. +This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR. +. +.It Fl -test-randomize +Randomize test execution order. This applies to both test file execution order +and queued tests within each file. This can help detect tests that rely on +shared state or execution order. +The seed used for randomization is printed in the test summary and can be +reused with \fB--test-random-seed\fR. +For detailed behavior and examples, see +randomizing tests execution order. +This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR. +. +.It Fl -test-reporter +A test reporter to use when running tests. See the documentation on +test reporters for more details. +. +.It Fl -test-reporter-destination +The destination for the corresponding test reporter. See the documentation on +test reporters for more details. +. +.It Fl -test-rerun-failures +A path to a file allowing the test runner to persist the state of the test +suite between runs. The test runner will use this file to determine which tests +have already succeeded or failed, allowing for re-running of failed tests +without having to re-run the entire test suite. The test runner will create this +file if it does not exist. +See the documentation on test reruns for more details. +. +.It Fl -test-shard +Test suite shard to execute in a format of \fB/\fR, where +.Bl -bullet +.It +\fBindex\fR is a positive integer, index of divided parts. +.It +\fBtotal\fR is a positive integer, total of divided part. +.El +This command will divide all tests files into \fBtotal\fR equal parts, +and will run only those that happen to be in an \fBindex\fR part. +For example, to split your tests suite into three parts, use this: +.Bd -literal +node --test --test-shard=1/3 +node --test --test-shard=2/3 +node --test --test-shard=3/3 +.Ed +. +.It Fl -test-skip-pattern +A regular expression that configures the test runner to skip tests +whose name matches the provided pattern. See the documentation on +filtering tests by name for more details. +If both \fB--test-name-pattern\fR and \fB--test-skip-pattern\fR are supplied, +tests must satisfy \fBboth\fR requirements in order to be executed. +. +.It Fl -test-timeout +A number of milliseconds the test execution will fail after. If unspecified, +subtests inherit this value from their parent. The default value is \fBInfinity\fR. +. +.It Fl -test-update-snapshots +Regenerates the snapshot files used by the test runner for snapshot testing. +. +.It Fl -throw-deprecation +Throw errors for deprecations. +. +.It Fl -title Ns = Ns Ar title +Set \fBprocess.title\fR on startup. +. +.It Fl -tls-cipher-list Ns = Ns Ar list +Specify an alternative default TLS cipher list. Requires Node.js to be built +with crypto support (default). +. +.It Fl -tls-keylog Ns = Ns Ar file +Log TLS key material to a file. The key material is in NSS \fBSSLKEYLOGFILE\fR +format and can be used by software (such as Wireshark) to decrypt the TLS +traffic. +. +.It Fl -tls-max-v1.2 +Set \fBtls.DEFAULT_MAX_VERSION\fR to 'TLSv1.2'. Use to disable support for +TLSv1.3. +. +.It Fl -tls-max-v1.3 +Set default \fBtls.DEFAULT_MAX_VERSION\fR to 'TLSv1.3'. Use to enable support +for TLSv1.3. +. +.It Fl -tls-min-v1.0 +Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1'. Use for compatibility with +old TLS clients or servers. +. +.It Fl -tls-min-v1.1 +Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.1'. Use for compatibility +with old TLS clients or servers. +. +.It Fl -tls-min-v1.2 +Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.2'. This is the default for +12.x and later, but the option is supported for compatibility with older Node.js +versions. +. +.It Fl -tls-min-v1.3 +Set default \fBtls.DEFAULT_MIN_VERSION\fR to 'TLSv1.3'. Use to disable support +for TLSv1.2, which is not as secure as TLSv1.3. +. +.It Fl -trace-deprecation +Print stack traces for deprecations. +. +.It Fl -trace-env +Print information about any access to environment variables done in the current Node.js +instance to stderr, including: +.Bl -bullet +.It +The environment variable reads that Node.js does internally. +.It +Writes in the form of \fBprocess.env.KEY = "SOME VALUE"\fR. +.It +Reads in the form of \fBprocess.env.KEY\fR. +.It +Definitions in the form of \fBObject.defineProperty(process.env, 'KEY', {...})\fR. +.It +Queries in the form of \fBObject.hasOwn(process.env, 'KEY')\fR, +\fBprocess.env.hasOwnProperty('KEY')\fR or \fB'KEY' in process.env\fR. +.It +Deletions in the form of \fBdelete process.env.KEY\fR. +.It +Enumerations inf the form of \fB...process.env\fR or \fBObject.keys(process.env)\fR. +.El +Only the names of the environment variables being accessed are printed. The values are not printed. +To print the stack trace of the access, use \fB--trace-env-js-stack\fR and/or +\fB--trace-env-native-stack\fR. +. +.It Fl -trace-env-js-stack +In addition to what \fB--trace-env\fR does, this prints the JavaScript stack trace of the access. +. +.It Fl -trace-env-native-stack +In addition to what \fB--trace-env\fR does, this prints the native stack trace of the access. +. +.It Fl -trace-event-categories +A comma separated list of categories that should be traced when trace event +tracing is enabled using \fB--trace-events-enabled\fR. +. +.It Fl -trace-event-file-pattern +Template string specifying the filepath for the trace event data, it +supports \fB${rotation}\fR and \fB${pid}\fR. +. +.It Fl -trace-events-enabled +Enables the collection of trace event tracing information. +. +.It Fl -trace-exit +Prints a stack trace whenever an environment is exited proactively, +i.e. invoking \fBprocess.exit()\fR. +. +.It Fl -trace-require-module Ns = Ns Ar mode +Prints information about usage of Loading ECMAScript modules using \fBrequire()\fR. +When \fBmode\fR is \fBall\fR, all usage is printed. When \fBmode\fR is \fBno-node-modules\fR, usage +from the \fBnode_modules\fR folder is excluded. +. +.It Fl -trace-sigint +Prints a stack trace on SIGINT. +. +.It Fl -trace-sync-io +Prints a stack trace whenever synchronous I/O is detected after the first turn +of the event loop. +. +.It Fl -trace-tls +Prints TLS packet trace information to \fBstderr\fR. This can be used to debug TLS +connection problems. +. +.It Fl -trace-uncaught +Print stack traces for uncaught exceptions; usually, the stack trace associated +with the creation of an \fBError\fR is printed, whereas this makes Node.js also +print the stack trace associated with throwing the value (which does not need +to be an \fBError\fR instance). +Enabling this option may affect garbage collection behavior negatively. +. +.It Fl -trace-warnings +Print stack traces for process warnings (including deprecations). +. +.It Fl -track-heap-objects +Track heap object allocations for heap snapshots. +. +.It Fl -unhandled-rejections Ns = Ns Ar mode +Using this flag allows to change what should happen when an unhandled rejection +occurs. One of the following modes can be chosen: +.Bl -bullet +.It +\fBthrow\fR: Emit \fBunhandledRejection\fR. If this hook is not set, raise the +unhandled rejection as an uncaught exception. This is the default. +.It +\fBstrict\fR: Raise the unhandled rejection as an uncaught exception. If the +exception is handled, \fBunhandledRejection\fR is emitted. +.It +\fBwarn\fR: Always trigger a warning, no matter if the \fBunhandledRejection\fR +hook is set or not but do not print the deprecation warning. +.It +\fBwarn-with-error-code\fR: Emit \fBunhandledRejection\fR. If this hook is not +set, trigger a warning, and set the process exit code to 1. +.It +\fBnone\fR: Silence all warnings. +.El +If a rejection happens during the command line entry point's ES module static +loading phase, it will always raise it as an uncaught exception. +. +.It Fl -use-bundled-ca , Fl -use-openssl-ca +Use bundled Mozilla CA store as supplied by current Node.js version +or use OpenSSL's default CA store. The default store is selectable +at build-time. +The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store +that is fixed at release time. It is identical on all supported platforms. +Using OpenSSL store allows for external modifications of the store. For most +Linux and BSD distributions, this store is maintained by the distribution +maintainers and system administrators. OpenSSL CA store location is dependent on +configuration of the OpenSSL library but this can be altered at runtime using +environment variables. +See \fBSSL_CERT_DIR\fR and \fBSSL_CERT_FILE\fR. +. +.It Fl -use-env-proxy +When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR +environment variables during startup, and tunnels requests over the +specified proxy. +This is equivalent to setting the \fBNODE_USE_ENV_PROXY=1\fR environment variable. +When both are set, \fB--use-env-proxy\fR takes precedence. +. +.It Fl -use-largepages Ns = Ns Ar mode +Re-map the Node.js static code to large memory pages at startup. If supported on +the target system, this will cause the Node.js static code to be moved onto 2 +MiB pages instead of 4 KiB pages. +The following values are valid for \fBmode\fR: +.Bl -bullet +.It +\fBoff\fR: No mapping will be attempted. This is the default. +.It +\fBon\fR: If supported by the OS, mapping will be attempted. Failure to map will +be ignored and a message will be printed to standard error. +.It +\fBsilent\fR: If supported by the OS, mapping will be attempted. Failure to map +will be ignored and will not be reported. +.El +. +.It Fl -use-system-ca +Node.js uses the trusted CA certificates present in the system store along with +the \fB--use-bundled-ca\fR option and the \fBNODE_EXTRA_CA_CERTS\fR environment variable. +On platforms other than Windows and macOS, this loads certificates from the directory +and file trusted by OpenSSL, similar to \fB--use-openssl-ca\fR, with the difference being +that it caches the certificates after first load. +On Windows and macOS, the certificate trust policy is similar to +Chromium's policy for locally trusted certificates, but with some differences: +On macOS, the following settings are respected: +.Bl -bullet +.It +Default and System Keychains.Bl -bullet +.It +Trust:.Bl -bullet +.It +Any certificate where the “When using this certificate” flag is set to “Always Trust” or +.It +Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Always Trust”. +.El +.It +The certificate must also be valid, with "X.509 Basic Policy" set to “Always Trust”. +.El +.El +On Windows, the following settings are respected: +.Bl -bullet +.It +Local Machine (accessed via \fBcertlm.msc\fR).Bl -bullet +.It +Trust:.Bl -bullet +.It +Trusted Root Certification Authorities +.It +Trusted People +.It +Enterprise Trust -> Enterprise -> Trusted Root Certification Authorities +.It +Enterprise Trust -> Enterprise -> Trusted People +.It +Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities +.It +Enterprise Trust -> Group Policy -> Trusted People +.El +.El +.It +Current User (accessed via \fBcertmgr.msc\fR).Bl -bullet +.It +Trust:.Bl -bullet +.It +Trusted Root Certification Authorities +.It +Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities +.El +.El +.El +On Windows and macOS, Node.js would check that the user settings for the trusted +certificates do not forbid them for TLS server authentication before using them. +Node.js currently does not support distrust/revocation of certificates +from another source based on system settings. +On other systems, Node.js loads certificates from the default certificate file +(typically \fB/etc/ssl/cert.pem\fR) and default certificate directory (typically +\fB/etc/ssl/certs\fR) that the version of OpenSSL that Node.js links to respects. +This typically works with the convention on major Linux distributions and other +Unix-like systems. If the overriding OpenSSL environment variables +(typically \fBSSL_CERT_FILE\fR and \fBSSL_CERT_DIR\fR, depending on the configuration +of the OpenSSL that Node.js links to) are set, the specified paths will be used to load +certificates instead. These environment variables can be used as workarounds +if the conventional paths used by the version of OpenSSL Node.js links to are +not consistent with the system configuration that the users have for some reason. +. +.It Fl -v8-options +Print V8 command-line options. +. +.It Fl -v8-pool-size Ns = Ns Ar num +Set V8's thread pool size which will be used to allocate background jobs. +If set to \fB0\fR then Node.js will choose an appropriate size of the thread pool +based on an estimate of the amount of parallelism. +The amount of parallelism refers to the number of computations that can be +carried out simultaneously in a given machine. In general, it's the same as the +amount of CPUs, but it may diverge in environments such as VMs or containers. +. +.It Fl v , Fl -version +Print node's version. +. +.It Fl -watch +Starts Node.js in watch mode. +When in watch mode, changes in the watched files cause the Node.js process to +restart. +By default, watch mode will watch the entry point +and any required or imported module. +Use \fB--watch-path\fR to specify what paths to watch. +This flag cannot be combined with +\fB--check\fR, \fB--eval\fR, \fB--interactive\fR, or the REPL. +Note: The \fB--watch\fR flag requires a file path as an argument and is incompatible +with \fB--run\fR or inline script input, as \fB--run\fR takes precedence and ignores watch +mode. If no file is provided, Node.js will exit with status code \fB9\fR. +.Bd -literal +node --watch index.js +.Ed +. +.It Fl -watch-kill-signal +Customizes the signal sent to the process on watch mode restarts. +.Bd -literal +node --watch --watch-kill-signal SIGINT test.js +.Ed +. +.It Fl -watch-path +Starts Node.js in watch mode and specifies what paths to watch. +When in watch mode, changes in the watched paths cause the Node.js process to +restart. +This will turn off watching of required or imported modules, even when used in +combination with \fB--watch\fR. +This flag cannot be combined with +\fB--check\fR, \fB--eval\fR, \fB--interactive\fR, \fB--test\fR, or the REPL. +Note: Using \fB--watch-path\fR implicitly enables \fB--watch\fR, which requires a file path +and is incompatible with \fB--run\fR, as \fB--run\fR takes precedence and ignores watch mode. +.Bd -literal +node --watch-path=./src --watch-path=./tests index.js +.Ed +This option is only supported on macOS and Windows. +An \fBERR_FEATURE_UNAVAILABLE_ON_PLATFORM\fR exception will be thrown +when the option is used on a platform that does not support it. +. +.It Fl -watch-preserve-output +Disable the clearing of the console when watch mode restarts the process. +.Bd -literal +node --watch --watch-preserve-output test.js +.Ed +. +.It Fl -zero-fill-buffers +Automatically zero-fills all newly allocated \fBBuffer\fR instances. +. + +.El +. +.Sh ENVIRONMENT +.Bl -tag -width 6n +.It Ev FORCE_COLOR Ar [1, 2, 3] +The \fBFORCE_COLOR\fR environment variable is used to +enable ANSI colorized output. The value may be: +.Bl -bullet +.It +\fB1\fR, \fBtrue\fR, or the empty string \fB''\fR indicate 16-color support, +.It +\fB2\fR to indicate 256-color support, or +.It +\fB3\fR to indicate 16 million-color support. +.El +When \fBFORCE_COLOR\fR is used and set to a supported value, both the \fBNO_COLOR\fR, +and \fBNODE_DISABLE_COLORS\fR environment variables are ignored. +Any other value will result in colorized output being disabled. +. +.It Ev NODE_COMPILE_CACHE Ar dir +Enable the module compile cache for the Node.js instance. See the documentation of +module compile cache for details. +. +.It Ev NODE_COMPILE_CACHE_PORTABLE Ar 1 +When set to 1, the module compile cache can be reused across different directory +locations as long as the module layout relative to the cache directory remains the same. +. +.It Ev NODE_DEBUG Ar module[,…] +\fB','\fR-separated list of core modules that should print debug information. +. +.It Ev NODE_DEBUG_NATIVE Ar module[,…] +\fB','\fR-separated list of core C++ modules that should print debug information. +. +.It Ev NODE_DISABLE_COLORS Ar 1 +When set, colors will not be used in the REPL. +. +.It Ev NODE_DISABLE_COMPILE_CACHE Ar 1 + +Disable the module compile cache for the Node.js instance. See the documentation of +module compile cache for details. +. +.It Ev NODE_EXTRA_CA_CERTS Ar file +When set, the well known "root" CAs (like VeriSign) will be extended with the +extra certificates in \fBfile\fR. The file should consist of one or more trusted +certificates in PEM format. A message will be emitted (once) with +\fBprocess.emitWarning()\fR if the file is missing or +malformed, but any errors are otherwise ignored. +Neither the well known nor extra certificates are used when the \fBca\fR +options property is explicitly specified for a TLS or HTTPS client or server. +This environment variable is ignored when \fBnode\fR runs as setuid root or +has Linux file capabilities set. +The \fBNODE_EXTRA_CA_CERTS\fR environment variable is only read when the Node.js +process is first launched. Changing the value at runtime using +\fBprocess.env.NODE_EXTRA_CA_CERTS\fR has no effect on the current process. +. +.It Ev NODE_ICU_DATA Ar file +Data path for ICU (\fBIntl\fR object) data. Will extend linked-in data when compiled +with small-icu support. +. +.It Ev NODE_NO_WARNINGS Ar 1 +When set to \fB1\fR, process warnings are silenced. +. +.It Ev NODE_OPTIONS Ar options... +A space-separated list of command-line options. \fBoptions...\fR are interpreted +before command-line options, so command-line options will override or +compound after anything in \fBoptions...\fR. Node.js will exit with an error if +an option that is not allowed in the environment is used, such as \fB-p\fR or a +script file. +If an option value contains a space, it can be escaped using double quotes: +.Bd -literal +NODE_OPTIONS='--require "./my path/file.js"' +.Ed +A singleton flag passed as a command-line option will override the same flag +passed into \fBNODE_OPTIONS\fR: +.Bd -literal +# The inspector will be available on port 5555 +NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555 +.Ed +A flag that can be passed multiple times will be treated as if its +\fBNODE_OPTIONS\fR instances were passed first, and then its command-line +instances afterwards: +.Bd -literal +NODE_OPTIONS='--require "./a.js"' node --require "./b.js" +# is equivalent to: +node --require "./a.js" --require "./b.js" +.Ed +Node.js options that are allowed are in the following list. If an option +supports both --XX and --no-XX variants, they are both supported but only +one is included in the list below. +.Bl -bullet +.It +\fB--allow-addons\fR +.It +\fB--allow-child-process\fR +.It +\fB--allow-ffi\fR +.It +\fB--allow-fs-read\fR +.It +\fB--allow-fs-write\fR +.It +\fB--allow-inspector\fR +.It +\fB--allow-net\fR +.It +\fB--allow-wasi\fR +.It +\fB--allow-worker\fR +.It +\fB--conditions\fR, \fB-C\fR +.It +\fB--cpu-prof-dir\fR +.It +\fB--cpu-prof-interval\fR +.It +\fB--cpu-prof-name\fR +.It +\fB--cpu-prof\fR +.It +\fB--diagnostic-dir\fR +.It +\fB--disable-proto\fR +.It +\fB--disable-sigusr1\fR +.It +\fB--disable-warning\fR +.It +\fB--disable-wasm-trap-handler\fR +.It +\fB--dns-result-order\fR +.It +\fB--enable-fips\fR +.It +\fB--enable-network-family-autoselection\fR +.It +\fB--enable-source-maps\fR +.It +\fB--entry-url\fR +.It +\fB--experimental-abortcontroller\fR +.It +\fB--experimental-addon-modules\fR +.It +\fB--experimental-detect-module\fR +.It +\fB--experimental-dtls\fR +.It +\fB--experimental-eventsource\fR +.It +\fB--experimental-ffi\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-package-map\fR +.It +\fB--experimental-print-required-tla\fR +.It +\fB--experimental-quic\fR +.It +\fB--experimental-require-module\fR +.It +\fB--experimental-shadow-realm\fR +.It +\fB--experimental-specifier-resolution\fR +.It +\fB--experimental-stream-iter\fR +.It +\fB--experimental-test-isolation\fR +.It +\fB--experimental-top-level-await\fR +.It +\fB--experimental-vfs\fR +.It +\fB--experimental-vm-modules\fR +.It +\fB--experimental-wasi-unstable-preview1\fR +.It +\fB--force-context-aware\fR +.It +\fB--force-fips\fR +.It +\fB--force-node-api-uncaught-exceptions-policy\fR +.It +\fB--frozen-intrinsics\fR +.It +\fB--heap-prof-dir\fR +.It +\fB--heap-prof-interval\fR +.It +\fB--heap-prof-name\fR +.It +\fB--heap-prof\fR +.It +\fB--heapsnapshot-near-heap-limit\fR +.It +\fB--heapsnapshot-signal\fR +.It +\fB--http-parser\fR +.It +\fB--icu-data-dir\fR +.It +\fB--import\fR +.It +\fB--input-type\fR +.It +\fB--insecure-http-parser\fR +.It +\fB--inspect-brk\fR +.It +\fB--inspect-port\fR, \fB--debug-port\fR +.It +\fB--inspect-publish-uid\fR +.It +\fB--inspect-wait\fR +.It +\fB--inspect\fR +.It +\fB--localstorage-file\fR +.It +\fB--max-http-header-size\fR +.It +\fB--max-old-space-size-percentage\fR +.It +\fB--napi-modules\fR +.It +\fB--network-family-autoselection-attempt-timeout\fR +.It +\fB--no-addons\fR +.It +\fB--no-async-context-frame\fR +.It +\fB--no-deprecation\fR +.It +\fB--no-experimental-global-navigator\fR +.It +\fB--no-experimental-repl-await\fR +.It +\fB--no-experimental-sqlite\fR +.It +\fB--no-experimental-strip-types\fR +.It +\fB--no-experimental-websocket\fR +.It +\fB--no-experimental-webstorage\fR +.It +\fB--no-extra-info-on-fatal-exception\fR +.It +\fB--no-force-async-hooks-checks\fR +.It +\fB--no-global-search-paths\fR +.It +\fB--no-network-family-autoselection\fR +.It +\fB--no-strip-types\fR +.It +\fB--no-warnings\fR +.It +\fB--no-webstorage\fR +.It +\fB--node-memory-debug\fR +.It +\fB--openssl-config\fR +.It +\fB--openssl-legacy-provider\fR +.It +\fB--openssl-shared-config\fR +.It +\fB--pending-deprecation\fR +.It +\fB--permission-audit\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-module\fR +.It +\fB--require\fR, \fB-r\fR +.It +\fB--secure-heap-min\fR +.It +\fB--secure-heap\fR +.It +\fB--snapshot-blob\fR +.It +\fB--test-coverage-branches\fR +.It +\fB--test-coverage-exclude\fR +.It +\fB--test-coverage-functions\fR +.It +\fB--test-coverage-include\fR +.It +\fB--test-coverage-lines\fR +.It +\fB--test-global-setup\fR +.It +\fB--test-isolation\fR +.It +\fB--test-name-pattern\fR +.It +\fB--test-only\fR +.It +\fB--test-random-seed\fR +.It +\fB--test-randomize\fR +.It +\fB--test-reporter-destination\fR +.It +\fB--test-reporter\fR +.It +\fB--test-rerun-failures\fR +.It +\fB--test-shard\fR +.It +\fB--test-skip-pattern\fR +.It +\fB--throw-deprecation\fR +.It +\fB--title\fR +.It +\fB--tls-cipher-list\fR +.It +\fB--tls-keylog\fR +.It +\fB--tls-max-v1.2\fR +.It +\fB--tls-max-v1.3\fR +.It +\fB--tls-min-v1.0\fR +.It +\fB--tls-min-v1.1\fR +.It +\fB--tls-min-v1.2\fR +.It +\fB--tls-min-v1.3\fR +.It +\fB--trace-deprecation\fR +.It +\fB--trace-env-js-stack\fR +.It +\fB--trace-env-native-stack\fR +.It +\fB--trace-env\fR +.It +\fB--trace-event-categories\fR +.It +\fB--trace-event-file-pattern\fR +.It +\fB--trace-events-enabled\fR +.It +\fB--trace-exit\fR +.It +\fB--trace-require-module\fR +.It +\fB--trace-sigint\fR +.It +\fB--trace-sync-io\fR +.It +\fB--trace-tls\fR +.It +\fB--trace-uncaught\fR +.It +\fB--trace-warnings\fR +.It +\fB--track-heap-objects\fR +.It +\fB--unhandled-rejections\fR +.It +\fB--use-bundled-ca\fR +.It +\fB--use-env-proxy\fR +.It +\fB--use-largepages\fR +.It +\fB--use-openssl-ca\fR +.It +\fB--use-system-ca\fR +.It +\fB--v8-pool-size\fR +.It +\fB--watch-kill-signal\fR +.It +\fB--watch-path\fR +.It +\fB--watch-preserve-output\fR +.It +\fB--watch\fR +.It +\fB--zero-fill-buffers\fR +.El +V8 options that are allowed are: +.Bl -bullet +.It +\fB--abort-on-uncaught-exception\fR +.It +\fB--disallow-code-generation-from-strings\fR +.It +\fB--enable-etw-stack-walking\fR +.It +\fB--expose-gc\fR +.It +\fB--interpreted-frames-native-stack\fR +.It +\fB--jitless\fR +.It +\fB--max-heap-size\fR +.It +\fB--max-old-space-size\fR +.It +\fB--max-semi-space-size\fR +.It +\fB--perf-basic-prof-only-functions\fR +.It +\fB--perf-basic-prof\fR +.It +\fB--perf-prof-unwinding-info\fR +.It +\fB--perf-prof\fR +.It +\fB--stack-trace-limit\fR +.El +\fB--perf-basic-prof-only-functions\fR, \fB--perf-basic-prof\fR, +\fB--perf-prof-unwinding-info\fR, and \fB--perf-prof\fR are only available on Linux. +\fB--enable-etw-stack-walking\fR is only available on Windows. +. +.It Ev NODE_PATH Ar path[:…] +\fB':'\fR-separated list of directories prefixed to the module search path. +On Windows, this is a \fB';'\fR-separated list instead. +. +.It Ev NODE_PENDING_DEPRECATION Ar 1 +When set to \fB1\fR, emit pending deprecation warnings. +Pending deprecations are generally identical to a runtime deprecation with the +notable exception that they are turned \fIoff\fR by default and will not be emitted +unless either the \fB--pending-deprecation\fR command-line flag, or the +\fBNODE_PENDING_DEPRECATION=1\fR environment variable, is set. Pending deprecations +are used to provide a kind of selective "early warning" mechanism that +developers may leverage to detect deprecated API usage. +. +.It Ev NODE_PENDING_PIPE_INSTANCES Ar instances +Set the number of pending pipe instance handles when the pipe server is waiting +for connections. This setting applies to Windows only. +. +.It Ev NODE_PRESERVE_SYMLINKS Ar 1 +When set to \fB1\fR, instructs the module loader to preserve symbolic links when +resolving and caching modules. +. +.It Ev NODE_REDIRECT_WARNINGS Ar file +When set, process warnings will be emitted to the given file instead of +printing to stderr. The file will be created if it does not exist, and will be +appended to if it does. If an error occurs while attempting to write the +warning to the file, the warning will be written to stderr instead. This is +equivalent to using the \fB--redirect-warnings=file\fR command-line flag. +. +.It Ev NODE_REPL_EXTERNAL_MODULE Ar file +Path to a Node.js module which will be loaded in place of the built-in REPL. +Overriding this value to an empty string (\fB''\fR) will use the built-in REPL. +. +.It Ev NODE_REPL_HISTORY Ar file +Path to the file used to store the persistent REPL history. The default path is +\fB~/.node_repl_history\fR, which is overridden by this variable. Setting the value +to an empty string (\fB''\fR or \fB' '\fR) disables persistent REPL history. +. +.It Ev NODE_SKIP_PLATFORM_CHECK Ar value +If \fBvalue\fR equals \fB'1'\fR, the check for a supported platform is skipped during +Node.js startup. Node.js might not execute correctly. Any issues encountered +on unsupported platforms will not be fixed. +. +.It Ev NODE_TEST_CONTEXT Ar value +If \fBvalue\fR equals \fB'child'\fR, test reporter options will be overridden and test +output will be sent to stdout in the TAP format. If any other value is provided, +Node.js makes no guarantees about the reporter format used or its stability. +. +.It Ev NODE_TLS_REJECT_UNAUTHORIZED Ar value +If \fBvalue\fR equals \fB'0'\fR, certificate validation is disabled for TLS connections. +This makes TLS, and HTTPS by extension, insecure. The use of this environment +variable is strongly discouraged. +. +.It Ev NODE_USE_ENV_PROXY Ar 1 + +When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR +environment variables during startup, and tunnels requests over the +specified proxy. +This can also be enabled using the \fB--use-env-proxy\fR command-line flag. +When both are set, \fB--use-env-proxy\fR takes precedence. +. +.It Ev NODE_USE_SYSTEM_CA Ar 1 +Node.js uses the trusted CA certificates present in the system store along with +the \fB--use-bundled-ca\fR option and the \fBNODE_EXTRA_CA_CERTS\fR environment variable. +This can also be enabled using the \fB--use-system-ca\fR command-line flag. +When both are set, \fB--use-system-ca\fR takes precedence. +. +.It Ev NODE_V8_COVERAGE Ar dir +When set, Node.js will begin outputting V8 JavaScript code coverage and +Source Map data to the directory provided as an argument (coverage +information is written as JSON to files with a \fBcoverage\fR prefix). +\fBNODE_V8_COVERAGE\fR will automatically propagate to subprocesses, making it +easier to instrument applications that call the \fBchild_process.spawn()\fR family +of functions. \fBNODE_V8_COVERAGE\fR can be set to an empty string, to prevent +propagation. +. +.It Ev NO_COLOR Ar +\fBNO_COLOR\fR is an alias for \fBNODE_DISABLE_COLORS\fR. The value of the +environment variable is arbitrary. +. +.It Ev OPENSSL_CONF Ar file +Load an OpenSSL configuration file on startup. Among other uses, this can be +used to enable FIPS-compliant crypto if Node.js is built with +\fB./configure --openssl-fips\fR. +If the \fB--openssl-config\fR command-line option is used, the environment +variable is ignored. +. +.It Ev SSL_CERT_DIR Ar dir +If \fB--use-openssl-ca\fR is enabled, or if \fB--use-system-ca\fR is enabled on +platforms other than macOS and Windows, this overrides and sets OpenSSL's directory +containing trusted certificates. +Be aware that unless the child environment is explicitly set, this environment +variable will be inherited by any child processes, and if they use OpenSSL, it +may cause them to trust the same CAs as node. +. +.It Ev SSL_CERT_FILE Ar file +If \fB--use-openssl-ca\fR is enabled, or if \fB--use-system-ca\fR is enabled on +platforms other than macOS and Windows, this overrides and sets OpenSSL's file +containing trusted certificates. +Be aware that unless the child environment is explicitly set, this environment +variable will be inherited by any child processes, and if they use OpenSSL, it +may cause them to trust the same CAs as node. +. +.It Ev TZ +The \fBTZ\fR environment variable is used to specify the timezone configuration. +While Node.js does not support all of the various ways that \fBTZ\fR is handled in +other environments, it does support basic timezone IDs (such as +\fB'Etc/UTC'\fR, \fB'Europe/Paris'\fR, or \fB'America/New_York'\fR). +It may support a few other abbreviations or aliases, but these are strongly +discouraged and not guaranteed. +.Bd -literal +$ TZ=Europe/Dublin node -pe "new Date().toString()" +Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time) +.Ed +. +.It Ev UV_THREADPOOL_SIZE Ar size +Set the number of threads used in libuv's threadpool to \fBsize\fR threads. +Asynchronous system APIs are used by Node.js whenever possible, but where they +do not exist, libuv's threadpool is used to create asynchronous node APIs based +on synchronous system APIs. Node.js APIs that use the threadpool are: +.Bl -bullet +.It +all \fBfs\fR APIs, other than the file watcher APIs and those that are explicitly +synchronous +.It +asynchronous crypto APIs such as \fBcrypto.pbkdf2()\fR, \fBcrypto.scrypt()\fR, +\fBcrypto.randomBytes()\fR, \fBcrypto.randomFill()\fR, \fBcrypto.generateKeyPair()\fR +.It +\fBdns.lookup()\fR +.It +all \fBzlib\fR APIs, other than those that are explicitly synchronous +.El +Because libuv's threadpool has a fixed size, it means that if for whatever +reason any of these APIs takes a long time, other (seemingly unrelated) APIs +that run in libuv's threadpool will experience degraded performance. In order to +mitigate this issue, one potential solution is to increase the size of libuv's +threadpool by setting the \fB'UV_THREADPOOL_SIZE'\fR environment variable to a value +greater than \fB4\fR (its current default value). However, setting this from inside +the process using \fBprocess.env.UV_THREADPOOL_SIZE=size\fR is not guaranteed to work +as the threadpool would have been created as part of the runtime initialisation +much before user code is run. For more information, see the libuv threadpool documentation. +. + +.El +. +.Sh BUGS +Bugs are tracked in GitHub Issues: +.Sy https://github.com/nodejs/node/issues +. +.Sh COPYRIGHT +Copyright Node.js contributors. +Node.js is available under the MIT license. +. +.Pp +Node.js also includes external libraries that are available under a variety of licenses. +See +.Sy https://github.com/nodejs/node/blob/HEAD/LICENSE +for the full license text. +. +.Sh SEE ALSO +Website: +.Sy https://nodejs.org/ +. +.Pp +Documentation: +.Sy https://nodejs.org/api/ +. +.Pp +GitHub repository and issue tracker: +.Sy https://github.com/nodejs/node diff --git a/src/node_options.cc b/src/node_options.cc index b7eadef850f75d..7f036cd04163de 100644 --- a/src/node_options.cc +++ b/src/node_options.cc @@ -461,6 +461,10 @@ void Parse( args, exec_args, v8_args, options, required_env_settings, errors); } +// XXX: If you add an option here, please also add it to doc/node.1 and +// doc/api/cli.md +// TODO(addaleax): Make that unnecessary. + DebugOptionsParser::DebugOptionsParser() { AddOption("--inspect-port", "set host:port for inspector", diff --git a/test/doctool/test-manpage-envvars.mjs b/test/parallel/test-cli-node-cli-manpage-env-vars.mjs similarity index 91% rename from test/doctool/test-manpage-envvars.mjs rename to test/parallel/test-cli-node-cli-manpage-env-vars.mjs index edf966bebb34f3..97bf4b19642257 100644 --- a/test/doctool/test-manpage-envvars.mjs +++ b/test/parallel/test-cli-node-cli-manpage-env-vars.mjs @@ -1,14 +1,9 @@ -import * as common from '../common/index.mjs'; - +import '../common/index.mjs'; import assert from 'node:assert'; import { createReadStream } from 'node:fs'; import { createInterface } from 'node:readline'; import { resolve, join } from 'node:path'; -if (common.isWindows) { - common.skip('`make doc` does not run on Windows'); -} - // This test checks that all the environment variables defined in the public CLI documentation (doc/api/cli.md) // are also documented in the manpage file (doc/node.1) and vice-versa (that all the environment variables // in the manpage are present in the CLI documentation) @@ -19,11 +14,11 @@ const cliMdEnvVarNames = await collectCliMdEnvVarNames(); const manpageEnvVarNames = await collectManPageEnvVarNames(); assert(cliMdEnvVarNames.size > 0, - 'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file', + 'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file' ); assert(manpageEnvVarNames.size > 0, - 'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file', + 'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file' ); for (const envVarName of cliMdEnvVarNames) { @@ -40,7 +35,7 @@ if (manpageEnvVarNames.size > 0) { } async function collectManPageEnvVarNames() { - const manPagePath = join(rootDir, 'out', 'doc', 'node.1'); + const manPagePath = join(rootDir, 'doc', 'node.1'); const fileStream = createReadStream(manPagePath); const rl = createInterface({ diff --git a/test/doctool/test-manpage-options.mjs b/test/parallel/test-cli-node-cli-manpage-options.mjs similarity index 93% rename from test/doctool/test-manpage-options.mjs rename to test/parallel/test-cli-node-cli-manpage-options.mjs index 919abcd8d5075c..9fd536a715420b 100644 --- a/test/doctool/test-manpage-options.mjs +++ b/test/parallel/test-cli-node-cli-manpage-options.mjs @@ -1,14 +1,9 @@ -import * as common from '../common/index.mjs'; - +import '../common/index.mjs'; import assert from 'node:assert'; import { createReadStream, readFileSync } from 'node:fs'; import { createInterface } from 'node:readline'; import { resolve, join } from 'node:path'; -if (common.isWindows) { - common.skip('`make doc` does not run on Windows'); -} - // This test checks that all the CLI flags defined in the public CLI documentation (doc/api/cli.md) // are also documented in the manpage file (doc/node.1) // Note: the opposite (that all variables in doc/node.1 are documented in the CLI documentation) @@ -19,7 +14,7 @@ const rootDir = resolve(import.meta.dirname, '..', '..'); const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md'); const cliMdContentsStream = createReadStream(cliMdPath); -const manPagePath = join(rootDir, 'out', 'doc', 'node.1'); +const manPagePath = join(rootDir, 'doc', 'node.1'); const manPageContents = readFileSync(manPagePath, { encoding: 'utf8' }); let insideOptionsSection = false; @@ -55,7 +50,7 @@ for await (const line of rl) { flagNames.length === 1 ? '' : 's' } (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${ flagNames.map((flag) => `"-${flag}"`).join(', ') - }`, + }` ); } } diff --git a/test/doctool/test-manpage-node-options.js b/test/parallel/test-cli-node-options-docs.js similarity index 97% rename from test/doctool/test-manpage-node-options.js rename to test/parallel/test-cli-node-options-docs.js index 3a3e83b77aced3..534c99c04de964 100644 --- a/test/doctool/test-manpage-node-options.js +++ b/test/parallel/test-cli-node-options-docs.js @@ -3,10 +3,6 @@ const common = require('../common'); if (process.config.variables.node_without_node_options) common.skip('missing NODE_OPTIONS support'); -if (common.isWindows) { - common.skip('`make doc` does not run on Windows'); -} - // Test options specified by env variable. const assert = require('assert'); @@ -26,7 +22,7 @@ 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, 'out', 'doc', 'node.1'); +const manPage = path.join(rootDir, 'doc', 'node.1'); const manPageText = fs.readFileSync(manPage, { encoding: 'utf8' }); // Documented in /doc/api/deprecations.md diff --git a/tools/install.py b/tools/install.py index 8fa042e5d33201..573d7423c9dc55 100755 --- a/tools/install.py +++ b/tools/install.py @@ -199,9 +199,9 @@ def files(options, action): action(options, [os.path.join(options.v8_dir, 'tools/lldb_commands.py')], 'share/doc/node/') if 'openbsd' in sys.platform: - action(options, ['out/doc/node.1'], 'man/man1/') + action(options, ['doc/node.1'], 'man/man1/') else: - action(options, ['out/doc/node.1'], 'share/man/man1/') + action(options, ['doc/node.1'], 'share/man/man1/') if 'true' == options.variables.get('node_install_npm'): npm_files(options, action)