NODE-20(1)

📦 version 20.20.2, in fedora 43, fedora 44

💖 NODE-20(1) — the node manual, but make it make sense 💖

okay bestie, pull up a chair, grab a boba 🧋, because we're about to go through node — the server-side JavaScript runtime — and I promise it's gonna be fun. manual page NODE-20(1), for the record. this is part 1, so don't you dare think we're done here.

✨ NAME ✨

node — server-side JavaScript runtime 🫶

🌈 SYNOPSIS 🌈

node [options] [v8-options] [-e string | script.js | -] [--]
     [arguments ...]
node inspect [-e string | script.js | - | <host>:<port>] ...
node [--v8-options]

look at that. three whole moods. pick your fighter 💅

🦋 DESCRIPTION 🦋

Node.js is literally a set of libraries for JavaScript that lets you use it outside of the browser. no cap. it's mainly focused on making simple, easy-to-build network clients and servers — like, that's its whole thing, that's its brand.

and listen: if you run node with no arguments at all? it starts a REPL. just you and your thoughts and an interactive prompt. iconic behavior honestly. ✨

💅 OPTIONS 💅

okay this is the big one. every single flag, no skips, no shortcuts. let's go 👑

  • - — an alias for stdin, same energy as using - in other command-line utilities. the script gets read from stdin, and whatever arguments are left over get passed to the script. cute.
  • -- — this one says "okay, command-line options are DONE." everything after it gets passed straight to the script.
heads up: if you haven't supplied a script filename or an eval/print script before this, then the next argument becomes the script filename. so like, order matters, bestie.
  • --abort-on-uncaught-exception — instead of just exiting, it aborts, which means a core file gets generated for analysis. 💀 dramatic but useful.
  • --allow-fs-read — allow file system read access when you're using the permission model.
  • --allow-fs-write — allow file system write access when you're using the permission model.
  • --allow-addons — allow using native addons when you're using the permission model.
  • --allow-child-process — allow spawning processes when you're using the permission model.
  • --allow-wasi — allow execution of WASI when you're using the permission model.
  • --allow-worker — allow creating worker threads when you're using the permission model.
  • --completion-bash — prints a source-able bash completion script for Node.js. tab-tab-tab your way to greatness 🎀
  • -C, --conditions string — use custom conditional exports conditions. string
  • --cpu-prof — starts the V8 CPU profiler right on start up, and writes the CPU profile to disk before exit. if --cpu-prof-dir isn't specified, the profile goes to the current working directory with a generated file name. ✨
  • --cpu-prof-dir — the directory where the CPU profiles made by --cpu-prof get placed. the default value is controlled by the --diagnostic-dir command-line option.
  • --cpu-prof-interval — the sampling interval, in microseconds, for the CPU profiles made by --cpu-prof. the default is 1000.
  • --cpu-prof-name — file name of the V8 CPU profile generated with --cpu-prof.
  • --diagnostic-dir — sets the directory for all diagnostic output files. default is the current working directory. (yes, it says that twice in the original, and honestly? it means it.) set the directory to which all diagnostic output files will be written to; defaults to current working directory. it affects the default output directory of: --cpu-prof-dir, --heap-prof-dir, --redirect-warnings.
  • --disable-proto=mode — disables the Object.prototype.__proto__ property. if mode is delete, the property gets removed entirely. if mode is throw, accessing the property throws an exception with the code ERR_PROTO_ACCESS.
  • --disable-wasm-trap-handler=mode — disables trap-handler-based WebAssembly bound checks and falls back to inline bound checks, so WebAssembly can run with limited virtual memory.
  • --disallow-code-generation-from-strings — makes built-in language features that generate code from strings — like eval and new Function — throw an exception instead. note: this does not affect the Node.js vm module. 🙈
  • --enable-fips — enables FIPS-compliant crypto at startup. requires Node.js to be built with ./configure --openssl-fips.
  • --enable-source-maps — enables Source Map V3 support for stack traces. your stack traces are about to get so much more readable, fr fr.
  • --experimental-default-type=type — interprets input via --eval or STDIN as either ES modules or CommonJS modules, for when --input-type is unspecified.
  • --experimental-import-meta-resolve — enables experimental ES modules support for import.meta.resolve().
  • --experimental-loader=module — specifies the module to use as a custom module loader.
  • --experimental-network-imports — enables experimental support for loading modules using import over https:.
  • --experimental-permission — enables the experimental permission model. 🔐
  • --experimental-policy — uses the specified file as a security policy.
  • --experimental-shadow-realm — use this flag to enable ShadowRealm support.
  • --experimental-test-coverage — enables code coverage in the test runner.
  • --experimental-test-module-mocks — enables module mocking in the test runner.
  • --experimental-eventsource — enables experimental support for the EventSource Web API.
  • --experimental-websocket — enables experimental support for the WebSocket API.
  • --no-experimental-fetch — disables experimental support for the Fetch API.
  • --no-experimental-global-customevent — disables exposition of the CustomEvent on the global scope.
  • --no-experimental-global-webcrypto — disables exposition of the Web Crypto API on the global scope.
  • --no-experimental-repl-await — disables top-level await keyword support in the REPL.
  • --experimental-vm-modules — enables experimental ES module support in the VM module.
  • --experimental-wasi-unstable-preview1 — enables experimental WebAssembly System Interface support. plot twist: this flag is no longer required, because WASI is enabled by default now. 🫶
  • --experimental-wasm-modules — enables experimental WebAssembly module support.
  • --force-context-aware — disables loading native addons that aren't context-aware.
  • --force-fips — forces FIPS-compliant crypto on startup. and no, you cannot disable it from script code. same requirements as --enable-fips. it's giving locked in 🔒
  • --frozen-intrinsics — enables experimental frozen intrinsics support.
  • --heapsnapshot-near-heap-limit=max_count — generates a heap snapshot when V8 heap usage approaches the heap limit. no more than the specified number of snapshots will be generated.
  • --heapsnapshot-signal=signal — generates a heap snapshot on the specified signal.
  • --heap-prof — starts the V8 heap profiler on start up, and writes the heap profile to disk before exit. if --heap-prof-dir isn't specified, the profile goes to the current working directory with a generated file name. ✨
  • --heap-prof-dir — the directory where the heap profiles made by --heap-prof get placed. the default value is controlled by the --diagnostic-dir command-line option.
  • --heap-prof-interval — the average sampling interval, in bytes, for the heap profiles made by --heap-prof. the default is 512 * 1024.
  • --heap-prof-name — file name of the V8 heap profile generated with --heap-prof.
  • --icu-data-dir=file — specify the ICU data load path. overrides NODE_ICU_DATA. 👑
  • --input-type=type — sets the module resolution type for input via --eval, --print or STDIN.
  • --inspect-brk=[host:]port — activates the inspector on host:port and breaks at the start of the user script.
  • --inspect-port=[host:]port — sets the host:port to be used when the inspector is activated.
  • --inspect-publish-uid=stderr,http — specifies how the inspector WebSocket URL is exposed. valid values are stderr and http. default is stderr,http.
  • --inspect-wait=[host:]port — activates the inspector on host:port and waits for a debugger to be attached. patient queen behavior 💅
  • --inspect=[host:]port — activates the inspector on host:port. default is 127.0.0.1:9229.

V8 Inspector integration lets you attach Chrome DevTools and IDEs to Node.js instances for debugging and profiling. it uses the Chrome DevTools Protocol. this is the good stuff, bestie 🔥

  • --insecure-http-parser — uses an insecure HTTP parser that accepts invalid HTTP headers. this may allow interoperability with non-conformant HTTP implementations. it may also allow request smuggling and other HTTP attacks that rely on invalid headers being accepted.
avoid using this option. like, genuinely. 🚩
  • --jitless — disables 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. 😭
this flag is inherited from V8 and is subject to change upstream. it may disappear in a non-semver-major release.
  • --max-http-header-size=size — specifies the maximum size of HTTP headers in bytes. defaults to 16 KiB.
  • --napi-modules — this option is a no-op. it's just kept around for compatibility. it's giving "still here for the plot" 🙈
  • --no-deprecation — silences deprecation warnings.
  • --no-extra-info-on-fatal-exception — hides extra information on the fatal exception that causes exit.
  • --no-force-async-hooks-checks — disables runtime checks for async_hooks. these will still be enabled dynamically when async_hooks is enabled.
  • --no-addons — disables the node-addons exports condition, and also disables loading native addons. when --no-addons is specified, calling process.dlopen or requiring a native C++ addon will fail and throw an exception.
  • --no-global-search-paths — don't search modules from global paths.
  • --no-warnings — silences all process warnings, including deprecations. 🤫
  • --node-memory-debug — enables extra debug checks for memory leaks in Node.js internals. usually this is only useful for developers debugging Node.js itself. (hi, that's a very specific person and we love them)
  • --openssl-config=file — loads an OpenSSL configuration file on startup. among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with ./configure --openssl-fips.
  • --pending-deprecation — emits pending deprecation warnings.
  • --policy-integrity=sri — tells Node.js to error before running any code if the policy doesn't have the specified integrity. it expects a Subresource Integrity string as a parameter.
  • --preserve-symlinks — tells the module loader to preserve symbolic links when resolving and caching modules other than the main module.
  • --preserve-symlinks-main — tells the module loader to preserve symbolic links when resolving and caching the main module. yes, it's a separate flag. yes, it matters. 🎀
  • --prof — generate V8 profiler output.
  • --prof-process — process V8 profiler output generated using the V8 option --prof.

okay that's the end of part 1, but we are SO not done. more parts coming, don't go anywhere bestie 🦋💜

  • --redirect-warnings=file — tired of warnings just vibing all over your stderr? This sends process warnings into the file you name instead. Clean terminal, clean mind.
  • --report-compact — writes diagnostic reports in a compact format, i.e. single-line JSON. No giant multi-line blob, just one tidy line.
  • --report-dir, --report-directory — the location at which the diagnostic report will be generated. The file name may be an absolute path. If it isn't, the default directory it will be written to is controlled by the --diagnostic-dir command-line option.
  • --report-filename — the name of the file to which the diagnostic report will be written. you get to name the baby.
  • --report-on-fatalerror — enables the diagnostic 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. Lowkey so useful for inspecting various diagnostic data elements like heap, stack, event loop state, resource consumption etc. so you can actually reason about the fatal error.
  • --report-on-signal — enables a diagnostic report to be generated upon receiving the specified (or predefined) signal to the running Node.js process. Default signal is SIGUSR2.
  • --report-signal — sets or resets the signal for diagnostic report generation (not supported on Windows, bestie). Default signal is SIGUSR2.
  • --report-uncaught-exception — enables a diagnostic report to be generated on un-caught exceptions. Chef's kiss when you're inspecting the JavaScript stack in conjunction with the native stack and other runtime environment data.
  • --secure-heap=n — specify the size of the OpenSSL secure heap. Any value less than 2 disables the secure heap. The default is 0. The value must be a power of two.
  • --secure-heap-min=n — specify the minimum allocation from the OpenSSL secure heap. The default is 2. The value must be a power of two.
  • --test — starts the Node.js command line test runner. periodt.
  • --test-concurrency — the maximum number of test files that the test runner CLI will execute concurrently.
  • --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.
  • --test-name-pattern — a regular expression that configures the test runner to only execute tests whose name matches the provided pattern.
  • --test-reporter — a test reporter to use when running tests.
  • --test-reporter-destination — the destination for the corresponding test reporter.
  • --test-only — configures the test runner to only execute top level tests that have the only option set.
  • --test-shard — test suite shard to execute, in a format of <index>/<total>.
  • --test-timeout — a number of milliseconds the test execution will fail after.
  • --throw-deprecation — throw errors for deprecations. no more silent shame, we're throwing hands (errors) instead
  • --title=title — specify process.title on startup.
  • --tls-cipher-list=list — specify an alternative default TLS cipher list. Requires Node.js to be built with crypto support. (Default)
  • --tls-keylog=file — log TLS key material to a file. The key material is in NSS SSLKEYLOGFILE format and can be used by software (such as Wireshark) to decrypt the TLS traffic. iykyk 🦋
  • --tls-max-v1.2 — set default maxVersion to 'TLSv1.2'. Use to disable support for TLSv1.3.
  • --tls-max-v1.3 — set default maxVersion to 'TLSv1.3'. Use to enable support for TLSv1.3.
  • --tls-min-v1.0 — set default minVersion to 'TLSv1'. Use for compatibility with old TLS clients or servers.
  • --tls-min-v1.1 — set default minVersion to 'TLSv1.1'. Use for compatibility with old TLS clients or servers.
  • --tls-min-v1.2 — set default minVersion to 'TLSv1.2'. This is the default for 12.x and later, but the option is supported for compatibility with older Node.js versions.
  • --tls-min-v1.3 — set default minVersion to 'TLSv1.3'. Use to disable support for TLSv1.2 in favour of TLSv1.3, which is more secure. we love a security glow-up ✨
  • --trace-atomics-wait — print short summaries of calls to Atomics.wait(). This flag is deprecated.
  • --trace-deprecation — print stack traces for deprecations.
  • --trace-event-categories categories — a comma-separated list of categories that should be traced when trace event tracing is enabled using --trace-events-enabled.
  • --trace-event-file-pattern pattern — a template string specifying the filepath for the trace event data. It supports ${rotation} and ${pid}.
  • --trace-events-enabled — enable the collection of trace event tracing information.
  • --trace-exit — prints a stack trace whenever an environment is exited proactively, i.e. invoking process.exit().
  • --trace-sigint — prints a stack trace on SIGINT.
  • --trace-sync-io — print a stack trace whenever synchronous I/O is detected after the first turn of the event loop.
  • --trace-tls — prints TLS packet trace information to stderr.
  • --trace-uncaught — print stack traces for uncaught exceptions. Usually, the stack trace associated with the creation of an Error is printed, whereas this makes Node.js also print the stack trace associated with throwing the value (which does not need to be an Error instance).
Heads up: enabling this option may affect garbage collection behavior negatively.
  • --trace-warnings — print stack traces for process warnings (including deprecations).
  • --track-heap-objects — track heap object allocations for heap snapshots.
  • --unhandled-rejections=mode — define the behavior for unhandled rejections. mode can be one of strict (raise an error), warn (enforce warnings) or none (silence warnings).
  • --use-bundled-ca, --use-openssl-ca — use the bundled Mozilla CA store as supplied by the 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 the Mozilla CA store that is fixed at release time. It is identical on all supported platforms.

Using the 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. The OpenSSL CA store location is dependent on configuration of the OpenSSL library, but this can be altered at runtime using environment variables.

See SSL_CERT_DIR and SSL_CERT_FILE.

  • --use-largepages=mode — re-map the Node.js static code to large memory pages at startup. If it's 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. big pages, big energy 🫶

mode must have one of the following values: off (the default value, meaning do not map), on (map and ignore failure, reporting it to stderr), or silent (map and silently ignore failure).

  • --v8-options — print V8 command-line options.
  • --v8-pool-size=num — set V8's thread pool size, which will be used to allocate background jobs. If set to 0 then V8 will choose an appropriate size of the thread pool based on the number of online processors. If the value provided is larger than V8's maximum, then the largest value will be chosen.
  • --zero-fill-buffers — automatically zero-fills all newly allocated Buffer and SlowBuffer instances.
  • -c, --check — check the script's syntax without executing it. Exits with an error code if the script is invalid.
  • -e, --eval string — evaluate string as JavaScript.
  • -h, --help — print command-line options. The output of this option is less detailed than this document. (yes, the very doc you're reading rn 💅)
  • -i, --interactive — open the REPL even if stdin does not appear to be a terminal.
  • -p, --print string — identical to -e, but prints the result.
  • -r, --require module — preload the specified module at startup. Follows require()'s module resolution rules. module may be either a path to a file, or a Node.js module name.
  • -v, --version — print node's version.

okay don't go anywhere, there's more coming 👀

🌈 ENVIRONMENT 🌈

okay bestie, this is the part where Node.js reads your vibes from the shell before it even gets going. Every single one of these is an environment variable, and they're all lowkey iconic. 👑

  • FORCE_COLOR — turns on ANSI colorized output, periodt. The value can be 1, true, or an empty string to say "gimme 16-color support", 2 for 256-color support, or 3 for the full 16 million-color glow-up ✨. When it's used and set to a supported value, both NO_COLOR and NODE_DISABLE_COLORS get straight-up ignored. Any other value? Colorized output is disabled. no cap.
  • NO_COLOR — literally just an alias for NODE_DISABLE_COLORS. same energy, different name 💅
  • NODE_DEBUG modules... — a comma-separated list of core modules that should print debug info. spill the tea, core modules 🫖
  • NODE_DEBUG_NATIVE modules... — same thing but for the C++ core modules. the native girlies get their own list 💀
  • NODE_DISABLE_COLORS — set it to 1 and the REPL stops using colors. that's it, that's the whole job.
  • NODE_EXTRA_CA_CERTS file — when you set this, the well-known "root" CAs (think VeriSign) get extended with the extra certificates sitting in file. The file should have one or more trusted certificates in PEM format. 🔐

If file is missing or misformatted, a message gets emitted once using process.emitWarning(), but any errors are otherwise ignored. she's forgiving like that 🙈

this environment variable gets ignored when node runs as setuid root or has Linux file capabilities set.

Also important: NODE_EXTRA_CA_CERTS is only read when the Node.js process is first launched. Changing the value at runtime with process.env.NODE_EXTRA_CA_CERTS does nothing to the current process. it's giving "too late bestie" 😭

  • NODE_ICU_DATA file — the data path for ICU (the Intl object) data. It'll extend linked-in data when compiled with small-icu support.
  • NODE_NO_WARNINGS — set it to 1 and process warnings are silenced. peace and quiet, we love to see it 🤫
  • NODE_OPTIONS options... — a space-separated list of command-line options, interpreted as if they'd been typed on the command line before the actual command (so they can be overridden). ⚠️ Node.js will exit with an error if you use an option that isn't allowed in the environment — like --print or a script file. not every option is invited to this party.
  • NODE_PATH directories... — a colon-separated list of directories that gets prefixed to the module search path. 🗂️
  • NODE_PENDING_DEPRECATION — set it to 1 and you'll get pending deprecation warnings emitted. the foreshadowing ✨
  • NODE_PRESERVE_SYMLINKS — set it to 1 and the module loader preserves symbolic links when resolving and caching modules. 🔗
  • NODE_REDIRECT_WARNINGS file — writes process warnings to file instead of printing them to stderr. Equivalent to passing --redirect-warnings file on the command line. two paths, one outcome 💖
  • NODE_REPL_HISTORY file — the path to the file where your persistent REPL history lives. The default is ~/.node_repl_history, and this variable overrides it. Set the value to an empty string ("" or " ") and persistent REPL history is disabled. your secrets are safe, main character 🕵️
  • NODE_REPL_EXTERNAL_MODULE file — the path to a Node.js module that gets loaded in place of the built-in REPL. Override this value to an empty string ('') and you get the built-in REPL back. 🎀
  • NODE_SKIP_PLATFORM_CHECK — set it to 1 and the check for a supported platform gets skipped during Node.js startup. ⚠️ Node.js might not execute correctly. Any issues you hit on unsupported platforms will not be fixed. you're on your own, babe, and we say that with love.
  • NODE_TLS_REJECT_UNAUTHORIZED — set it to 0 and TLS certificate validation is disabled. 🚨 huge red flag energy, do this only if you truly know what you're doing.
  • NODE_V8_COVERAGE dir — when set, Node.js writes JavaScript code coverage information to dir. slay, now you know what your tests actually touched 📊
  • OPENSSL_CONF file — loads an OpenSSL configuration file on startup. Among other uses, this can enable FIPS-compliant crypto if Node.js was built with ./configure --openssl-fips.

If the --openssl-config command-line option is used, this environment variable gets ignored. sorry bestie, the command line won this one 💅

  • SSL_CERT_DIR dir — if --use-openssl-ca is enabled, this overrides and sets OpenSSL's directory containing trusted certificates.
  • SSL_CERT_FILE file — if --use-openssl-ca is enabled, this overrides and sets OpenSSL's file containing trusted certificates.
  • TZ — specify the timezone configuration. ⏰ (yes, it's just that. a whole timezone, two little letters.)
  • UV_THREADPOOL_SIZE size — sets the number of threads used in libuv's threadpool to size. 🧵

🐛 BUGS 🐛

Bugs are tracked in GitHub Issues: https://github.com/nodejs/node/issues

found a lil glitch? go tell the repo. they're tracking them, fr fr. 📝

Copyright Node.js contributors. Node.js is available under the MIT license.

Node.js also includes external libraries that are available under a variety of licenses. See https://github.com/nodejs/node/blob/HEAD/LICENSE for the full license text.

🦋 SEE ALSO 🦋

and that's the whole page, bestie 🫶 this was the NODE(1) manual, dated 2018, and you read every single line of it. not me being proud of you 😭 go write some absolutely iconic code, and remember: read the docs, check the flags, and never disable TLS validation in prod. mwah 💖✨🎀

📦 where this page comes from