Configuration

There are four "configuration" surfaces in Node.js, all related but separate.

1. Build-time: ./configure

configure.py writes a single config.gypi consumed by node.gyp. The full flag list is ./configure --help. Categories:

• Variant: --debug, --ninja, --shared (build libnode), --prefix, --dest-cpu, --cross-compiling.
• Snapshots: --node-snapshot, --without-node-snapshot, --without-code-cache.
• OpenSSL: --shared-openssl, --openssl-no-asm, --openssl-is-fips, --openssl-fips.
• ICU: --with-intl=full-icu|small-icu|system-icu|none.
• Vendored deps switches: --shared-zlib, --shared-libuv, --shared-cares, --shared-nghttp2, --shared-brotli, --shared-ada, --shared-simdjson, --shared-sqlite, etc. Each replaces the corresponding deps/ library with the system one.
• Sanitizers: --enable-asan, --enable-ubsan, --enable-tsan.
• Optional features: --without-ssl, --without-intl, --without-inspector, --without-amaro, --without-quic, --without-corepack, --without-npm.
• Cross-build / Android: --dest-os, --dest-cpu, --cross-compiling, the android-configure driver script.
• Profiling: --prof, --enable-d8, --enable-vtune-profiling.

The result is exposed at runtime through process.config.variables.

2. Runtime: CLI flags

Defined in src/node_options.cc (~87K). --help prints the exhaustive list and doc/api/cli.md is the prose documentation.

Categories include:

• Module loading: --experimental-loader, --experimental-strip-types, --input-type, --require, --import.
• Snapshots: --snapshot-blob, --build-snapshot, --no-node-snapshot.
• Inspector: --inspect, --inspect-brk, --inspect-publish-uid, --inspect-port, --inspect-wait.
• Permission Model: --permission, --allow-fs-read, --allow-net=…, etc. (see Permission Model).
• Crashes / reports: --report-on-fatalerror, --report-on-signal, --report-uncaught-exception, --report-dir, --abort-on-uncaught-exception.
• Tracing: --trace-events-enabled, --trace-event-categories, --trace-uncaught.
• Performance: --max-old-space-size, --max-semi-space-size, --use-largepages.
• Watch mode: --watch, --watch-path, --watch-preserve-output.
• Test runner: --test, --test-name-pattern, --test-isolation, --experimental-test-coverage.

A flag whose name starts with --no- (e.g. --no-deprecation) is the negation of the named option.

3. Runtime: NODE_* environment variables

Documented in doc/api/cli.md § "Environment variables":

• NODE_OPTIONS — extra CLI flags (subset whitelisted in node_options.cc).
• NODE_PATH — extra search paths for CJS resolution.
• NODE_DEBUG / NODE_DEBUG_NATIVE — debug-log areas.
• NODE_DISABLE_COLORS / NO_COLOR — output color toggles.
• NODE_ENV — informational; not interpreted by core.
• NODE_EXTRA_CA_CERTS — append to TLS trust store.
• NODE_NO_WARNINGS — suppress process warnings.
• NODE_PRESERVE_SYMLINKS, NODE_PRESERVE_SYMLINKS_MAIN — module-resolution toggles.
• NODE_REPL_HISTORY — REPL history path.
• NODE_TLS_REJECT_UNAUTHORIZED — debug-only override for TLS validation.
• NODE_USE_ENV_PROXY — undici proxy support.
• UV_THREADPOOL_SIZE — libuv thread-pool size (passes through to libuv).
• OPENSSL_CONF — OpenSSL config; honoured by the bundled OpenSSL.

4. Runtime: --experimental-default-config-file / node-config-schema.json

Node 22 introduced --experimental-default-config-file which reads a JSON document validated against doc/node-config-schema.json and applies it as default flag values. The implementation is src/node_config_file.cc. It accepts a subset of NODE_OPTIONS-permitted flags; new flags must be added to the schema.

The schema is the single place to look for "what can a config file actually set".

Where each lives at runtime

Surface	Visible from JS as
Build-time GYP vars	process.config.variables
configure flags	process.config.target_defaults
Runtime CLI options	process.execArgv
Environment vars	process.env
Config file values	merged into the option set; visible via getters in lib/internal/options.js