proxy-agent

proxy-agent is a Node.js http.Agent that transparently routes outbound HTTP and HTTPS requests through whatever proxy your environment dictates. It reads the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables (via proxy-from-env) and, based on the proxy URL’s protocol, delegates to the appropriate low-level agent — http-proxy-agent, https-proxy-agent, socks-proxy-agent, or pac-proxy-agent.

Instead of wiring up per-protocol proxy logic yourself, you construct a single ProxyAgent and pass it to any Node HTTP client. An internal LRU cache re-uses agent instances across requests to the same proxy, so repeated calls stay cheap. It is the top-level convenience package in TooTallNate’s proxy-agents monorepo and is depended on across the npm ecosystem.

What You Get

• A single ProxyAgent class that plugs into any Node.js HTTP/HTTPS client
• Automatic protocol-to-agent mapping across http, https, socks(4/5), and pac+* proxy URLs
• Environment-variable-driven proxy selection via proxy-from-env (HTTP_PROXY / HTTPS_PROXY / NO_PROXY)
• An LRU cache that transparently re-uses agent instances for repeated requests to the same proxy
• First-class TypeScript types and a pluggable getProxyForUrl callback for dynamic proxy resolution

Common Use Cases

• Making outbound HTTP requests from apps that must honor corporate proxy settings
• Supporting multiple proxy protocols (SOCKS, HTTP, PAC) behind one agent without branching code
• Routing traffic through PAC-file-configured proxies in enterprise environments
• Adding proxy support to CLI tools and libraries that accept a standard http.Agent

Under The Hood

Architecture — The entire public surface lives in packages/proxy-agent/src/index.ts (~183 lines). ProxyAgent extends Agent from agent-base, so it slots into Node’s standard http.Agent contract. A static proxies map keys every supported protocol (http, https, socks/socks4/socks4a/socks5/socks5h, pac+data/file/ftp/http/https) to a pair of lazy loaders — one agent constructor for plaintext requests and one for secure/WebSocket requests. The core connect(req, opts) method reconstructs the request URL from the host header and req.path, calls getProxyForUrl to resolve a proxy string, and short-circuits to a default httpAgent/httpsAgent when no proxy applies. Otherwise it builds an LRU cache key of protocol+proxy, and on a miss parses the proxy URL, validates its protocol, dynamically imports the matching underlying agent, instantiates it, and caches it.

Tech Stack — Written in TypeScript targeting Node.js >= 20, shipped as ESM ("type": "module"). Runtime dependencies are the sibling monorepo agents (agent-base, http-proxy-agent, https-proxy-agent, socks-proxy-agent, pac-proxy-agent, all workspace:*) plus lru-cache for instance caching, proxy-from-env for env-var proxy resolution, and debug for tracing. Built with tsc, tested with Vitest, linted with ESLint; the monorepo uses pnpm workspaces and Turborepo.

Code Quality — Tight, single-file implementation with clear separation between the protocol table, validation (isValidProtocol type guard), and the connect flow. Types are precise: ProxyAgentOptions is an intersection of every underlying agent’s option type, and ValidProtocol is derived from the agents’ own protocols tuples. debug calls trace cache hits and proxy decisions. The package ships a dedicated test/test.ts (~390 lines) exercising real HTTP/HTTPS/SOCKS proxy servers, so behavior is well covered rather than merely unit-mocked.

API Design — Minimal and ergonomic: new ProxyAgent() with zero arguments covers the common case, since routing is inferred entirely from environment variables, and the agent drops into any client that accepts an http.Agent. Advanced control is available through a single options object and an optional getProxyForUrl callback for dynamic resolution. The README’s protocol table and one-call example make onboarding fast; the main friction is understanding upstream proxy-from-env env-var semantics.