How to Configure a Proxy in Node.js

The https-proxy-agent package is the foundation for proxy support in most Node.js HTTP clients. It creates an Agent instance that tunnels HTTPS requests through an HTTP CONNECT proxy. Install both http-proxy-agent and https-proxy-agent for complete protocol coverage.

import { HttpsProxyAgent } from 'https-proxy-agent';
import fetch from 'node-fetch';

const agent = new HttpsProxyAgent('http://USER:PASS@gw.knoxproxy.com:7000');

const response = await fetch('https://httpbin.org/ip', { agent });
const data = await response.json();
console.log(data.origin); // Proxy exit IP

The agent handles the CONNECT tunnel setup, TLS negotiation, and credential authentication transparently. You create it once and reuse it across multiple requests. For SOCKS5 proxies, use the socks-proxy-agent package with the same pattern, pointing at port 7001 for KnoxProxy.

Node.js 18+ includes a built-in fetch powered by undici. To route native fetch requests through a proxy, use undici's ProxyAgent and the setGlobalDispatcher function. This approach requires no third-party packages beyond undici itself.

import { ProxyAgent, setGlobalDispatcher } from 'undici';

const proxyAgent = new ProxyAgent({
  uri: 'http://USER:PASS@gw.knoxproxy.com:7000',
  requestTls: { rejectUnauthorized: true },
});

// Global dispatcher -- all fetch calls use the proxy
setGlobalDispatcher(proxyAgent);

const response = await fetch('https://httpbin.org/ip');
const data = await response.json();
console.log(data);

Setting a global dispatcher affects all fetch calls in the process, which is convenient for scrapers but may not be suitable for applications that need to mix proxied and direct traffic. For per-request control, pass the dispatcher option to individual fetch calls instead of setting it globally.