Repository navigation
Description
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:
- Node's built-in
fetch()ignoreshttp.Agentoptions. engines.nodeis currently>=22.19.0, and Node<22.21.0lacks built-in support for proxy environment variables (HTTP_PROXY,HTTPS_PROXY,NO_PROXY) infetch().
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) introducedhttp.setGlobalProxyFromEnv()innode:http, which enables built-inHTTP_PROXY/HTTPS_PROXY/NO_PROXYsupport on globalfetch()(andnode: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-proxyorNODE_USE_ENV_PROXY=1. Settingprocess.env.NODE_USE_ENV_PROXY = '1'from JS after Node boots does not activate it, and#!/usr/bin/env -S node --use-env-proxyinpackages/cli/src/cli.jsis not portable across all POSIX environments or Windows npm shims. - Milestone: Bumping
engines.nodeto>=24.14.0(e.g., when dropping Node 22 LTS ahead of/around its April 30, 2027 EOL) lets@lhci/clicallhttp.setGlobalProxyFromEnv()cleanly and deleteproxy-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 forHTTP_PROXY/HTTPS_PROXY/NO_PROXYbehindNODE_USE_ENV_PROXY=1/node --use-env-proxy. - We could bump
engines.nodeto>=22.21.0and dropproxy-agentsooner only if we accept requiring proxied users to setNODE_USE_ENV_PROXY=1(or invokenode --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). Unlikeproxy-agent, it does not supportALL_PROXY,socks:///socks5://proxies, or.pacauto-config URLs. options.agentinpackages/cli/src/fetch.js: Nothing inside LHCI passes{agent}topackages/cli/src/fetch.js(only unit tests inpackages/cli/test/fetch.test.jsexercise it), though droppingfetchWithAgentassumes no external consumers rely onpackages/cli/src/fetch.jsaccepting anhttp.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-agentfrompackages/cli/package.jsonand updateyarn.lock. - Replace
packages/cli/src/fetch.js(fetchWithAgent+ProxyAgent) with nativefetch()(callinghttp.setGlobalProxyFromEnv()for Option A, or documentingNODE_USE_ENV_PROXY=1for Option B). - Update
packages/cli/test/fetch.test.jsand release notes covering Node requirement and lack of SOCKS/PAC/ALL_PROXYsupport.
Activity