Skip to content

Remove proxy-agent once minimum Node.js version supports built-in env proxy configuration #1213

Open

Description

@connorjclark

Context

PR #1208 replaces isomorphic-fetch with Node's native global fetch(), removing node-fetch and its URL/polyfill dependencies from runtime installs. However, packages/cli/src/fetch.js still keeps proxy-agent@^8.0.2 (along with a ~90-line fetchWithAgent wrapper built on node:http / node:https) because:

  1. Node's built-in fetch() ignores http.Agent options.
  2. engines.node is currently >=22.19.0, and Node <22.21.0 lacks built-in support for proxy environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) in fetch().

proxy-agent is only used in packages/cli/src/fetch.js (consumed by upload and wizard), yet it pulls 28 unique transitive packages into @lhci/cli's published dependency tree (including http-proxy-agent, https-proxy-agent, socks-proxy-agent, socks, pac-proxy-agent, pac-resolver, quickjs-wasi, esprima, escodegen, degenerator, basic-ftp, and proxy-from-env). Removing it would substantially trim @lhci/cli's third-party runtime footprint.

When can proxy-agent be removed?

There are two possible Node.js milestones depending on whether environment-variable proxy handling should stay automatic or require user opt-in:

Option A: Zero-config automatic proxy support (Recommended) — requires Node.js >=24.14.0

  • Node.js v24.14.0 (backport of v25.4.0's nodejs/node#60953; not backported to Node 22) introduced http.setGlobalProxyFromEnv() in node:http, which enables built-in HTTP_PROXY / HTTPS_PROXY / NO_PROXY support on global fetch() (and node:http/node:https) programmatically at runtime.
  • Why Node 22 isn't seamless without a wrapper: Node v22.21.0+ only supports env proxies when opted in at process startup via --use-env-proxy or NODE_USE_ENV_PROXY=1. Setting process.env.NODE_USE_ENV_PROXY = '1' from JS after Node boots does not activate it, and #!/usr/bin/env -S node --use-env-proxy in packages/cli/src/cli.js is not portable across all POSIX environments or Windows npm shims.
  • Milestone: Bumping engines.node to >=24.14.0 (e.g., when dropping Node 22 LTS ahead of/around its April 30, 2027 EOL) lets @lhci/cli call http.setGlobalProxyFromEnv() cleanly and delete proxy-agent + fetchWithAgent.

Option B: Earlier removal on Node 22 — requires Node.js >=22.21.0 + NODE_USE_ENV_PROXY=1 opt-in

  • Node.js v22.21.0 introduced built-in fetch() support for HTTP_PROXY / HTTPS_PROXY / NO_PROXY behind NODE_USE_ENV_PROXY=1 / node --use-env-proxy.
  • We could bump engines.node to >=22.21.0 and drop proxy-agent sooner only if we accept requiring proxied users to set NODE_USE_ENV_PROXY=1 (or invoke node --use-env-proxy) as an explicit breaking change.

Behavioral Tradeoffs / Edge Cases to Verify

  • Supported proxy features: Node's native env proxy support covers HTTP and HTTPS proxies via HTTP_PROXY / HTTPS_PROXY / NO_PROXY (and lowercase equivalents). Unlike proxy-agent, it does not support ALL_PROXY, socks:// / socks5:// proxies, or .pac auto-config URLs.
  • options.agent in packages/cli/src/fetch.js: Nothing inside LHCI passes {agent} to packages/cli/src/fetch.js (only unit tests in packages/cli/test/fetch.test.js exercise it), though dropping fetchWithAgent assumes no external consumers rely on packages/cli/src/fetch.js accepting an http.Agent.

Checklist when unblocked

  • Bump engines.node (and CI / Docker / docs Node versions) to >=24.14.0 (Option A) or >=22.21.0 (Option B).
  • Remove proxy-agent from packages/cli/package.json and update yarn.lock.
  • Replace packages/cli/src/fetch.js (fetchWithAgent + ProxyAgent) with native fetch() (calling http.setGlobalProxyFromEnv() for Option A, or documenting NODE_USE_ENV_PROXY=1 for Option B).
  • Update packages/cli/test/fetch.test.js and release notes covering Node requirement and lack of SOCKS/PAC/ALL_PROXY support.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions