node-fetch Proxy Integration

node-fetch Proxy Setup

node-fetch is a lightweight HTTP client for Node.js that implements the browser Fetch API. Unlike browsers, Node.js does not natively route fetch requests through system proxies, so you need a proxy agent library to direct traffic through Hex Proxies. The most common choice is `https-proxy-agent`.

Installation

npm install node-fetch https-proxy-agent

Basic Proxy Configuration

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

const agent = new HttpsProxyAgent('http://user:pass@gate.hexproxies.com:8080');
const res = await fetch('https://httpbin.org/ip', { agent });
const data = await res.json();
console.log(data);

IP Whitelist Authentication

Whitelist your server IP in the Hex Proxies dashboard and omit credentials:

const agent = new HttpsProxyAgent('http://gate.hexproxies.com:8080');

SOCKS5 Proxy with node-fetch

Use `socks-proxy-agent` for SOCKS5 connections:

npm install socks-proxy-agent

import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5://user:pass@gate.hexproxies.com:1080');
const res = await fetch('https://httpbin.org/ip', { agent });

Geo-Targeted Requests

Append targeting parameters to your username:

const agent = new HttpsProxyAgent('http://user-country-de:pass@gate.hexproxies.com:8080');

Best Practices

• Reuse the agent instance across multiple requests to avoid creating new TCP connections for each call.
• Use rotation for scraping at scale — create a new agent per request if you want a fresh IP each time, or reuse for sticky sessions.
• Set timeouts using AbortController to prevent hanging requests.
• Handle errors with try/catch around fetch calls — proxy connection failures throw network errors.

Troubleshooting

• FetchError: request to ... failed: Verify proxy host, port, and credentials. Ensure outbound port 8080 is accessible.
• 407 Proxy Authentication Required: Check username and password. URL-encode special characters.
• UNABLE_TO_VERIFY_LEAF_SIGNATURE: Update Node.js or set `NODE_TLS_REJECT_UNAUTHORIZED=0` for testing only.
• Slow responses: Residential proxies have 1-3 second latency. Use AbortController with a 30-second timeout.