Enable Node’s Built-In Proxy Support at Startup

Use Node’s environment proxy switch with the correct fetch and http/https version thresholds and understand its client scope.

Node can read proxy environment variables itself when its built-in support is enabled at process startup. The available clients depend on the runtime version:

  • Built-in fetch supports NODE_USE_ENV_PROXY from Node 24.0.0, with a backport to 22.21.0.
  • Built-in node:http and node:https support through their default global agents starts at 24.5.0, also backported to 22.21.0.
  • The --use-env-proxy command-line switch starts at 24.5.0 and 22.21.0.

On a compatible release, this POSIX-shell example sets one corporate HTTP proxy for both destination schemes:

export HTTP_PROXY=http://proxy.example.net:8080
export HTTPS_PROXY=http://proxy.example.net:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example

node --use-env-proxy app.js

The HTTPS_PROXY name selects the route for HTTPS destinations; the URL can still name an HTTP proxy. Adjust NO_PROXY to the destinations that should bypass it. For an independent public-URL test with no proxy account, an HTTP entry from the HTTP proxy list can supply both proxy values while the required internal bypasses remain.

The environment-switch form is an alternative:

export NODE_USE_ENV_PROXY=1
node app.js

Set the routing variables before launching Node with either form. Assigning the opt-in flag to process.env after startup does not rerun the startup initialization.

Check the HTTP client actually in use

The default global agents are relevant to http and https calls that use them. A library with its own custom agent or dispatcher controls its own transport; raw TCP sockets are outside this HTTP routing feature. For a compatible Undici client, an explicit ProxyAgent dispatcher is a separate client-local interface.

If an application replaces a global agent, inspect that replacement before assuming it retains the startup proxy behavior. Likewise, npm’s registry configuration is a separate tool setting and does not prove how app.js routes requests.

For a corporate TLS trust requirement, configure the appropriate trusted CA for the runtime. Enabling proxy routing does not require disabling certificate verification.

Mikanda mikatakata