proxy-from-env

proxy-from-env is a small, focused Node.js utility that answers one question correctly: given a target URL, what proxy (if any) should handle the request, based on the standard HTTP_PROXY/HTTPS_PROXY/*_PROXY, ALL_PROXY, and NO_PROXY environment variables? It implements the de-facto conventions established by tools like curl and wget - protocol-specific proxy variables, NO_PROXY host/port matching with wildcard and dot-prefix rules, and ALL_PROXY as a fallback - so applications don’t have to reimplement this logic themselves.

The library exports a single function, getProxyForUrl, and deliberately does nothing else: it does not perform the proxying itself, leaving that to the caller (commonly paired with packages like https-proxy-agent or proxy-agent). This narrow scope has made it a foundational, widely-depended-upon piece of the Node.js HTTP tooling ecosystem.

What You Get

• A single getProxyForUrl(url) function accepting a string, URL instance, or legacy url.parse()-shaped object
• Protocol-aware proxy resolution - HTTPS_PROXY for https: URLs, FTP_PROXY for ftp:, WS_PROXY/WSS_PROXY for WebSocket URLs, etc.
• NO_PROXY support with exact host matches, * to disable all proxying, dot-prefix/wildcard suffix matching, and optional port matching
• ALL_PROXY fallback when no protocol-specific variable is set
• Both ESM (index.js) and CommonJS (index.cjs) entry points via package exports

Common Use Cases

• Adding standard corporate-proxy support to a custom HTTP client without reimplementing environment-variable parsing
• Building a proxy-aware http.Agent (as https-proxy-agent/proxy-agent do) that decides per-request whether to route through a proxy
• Respecting NO_PROXY exclusion rules so internal/intranet hosts bypass a configured proxy while external requests use it
• Ensuring consistent proxy behavior across a Node.js tool by matching the conventions used by curl, wget, and Python’s urllib

Under The Hood

Architecture - The entire implementation lives in a single ~100-line index.js: getProxyForUrl parses the input into a URL (via a small parseUrl helper wrapping the WHATWG URL constructor), extracts protocol/hostname/port, strips brackets/ports consistently for IPv6 hosts, calls a private shouldProxy(hostname, port) to evaluate NO_PROXY rules, and finally reads the appropriate *_proxy/all_proxy environment variable via a getEnv helper that checks both lowercase and uppercase variants (lowercase wins). Tech Stack - Zero-dependency, pure JavaScript (100% JS) targeting Node.js 10+, dual-published as ESM (index.js) and CommonJS (index.cjs), linted with ESLint’s flat config (eslint.config.mjs). Code Quality - test.js is nearly 5x the size of the implementation itself (465 vs 103 lines) and is run via Node’s built-in node --test runner with coverage reporting support, indicating thorough behavioral coverage of the NO_PROXY matching rules, IPv6 handling, and case-insensitive environment variable resolution; a separate test-require.cjs specifically verifies the CommonJS entry point still works. API Design - A single exported function with no configuration object, options, or classes to learn - callers pass a URL and get back a proxy URL string or empty string, mirroring exactly what curl/wget users already expect from proxy environment variables.