Node.js Proxy Setup

Node.js does not include built-in proxy support in its HTTP client. Unlike Python where you pass a dictionary, Node.js requires an agent object that intercepts outgoing connections and routes them through the proxy tunnel. The https-proxy-agent package is the standard solution, compatible with axios, node-fetch, and the native http/https modules.

Starting with Node.js 18, the built-in undici module offers a ProxyAgent dispatcher that works with the global fetch API. This eliminates the need for third-party packages in modern Node.js environments, though https-proxy-agent remains necessary for axios and older codebases.

Prerequisites

Before you begin, make sure you have: - An active Hex Proxies account with proxy credentials - Node.js 18+ - npm or yarn - https-proxy-agent package

Installation

npm install https-proxy-agent

Basic Proxy Configuration

Create an HttpsProxyAgent instance with your Hex Proxies gateway URL. This agent handles CONNECT tunneling, credential negotiation, and keep-alive management automatically.

import axios from 'axios';

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

// Axios with proxy agent const response = await axios.get('https://httpbin.org/ip', { httpsAgent: agent, timeout: 30000, }); console.log(response.data);

// Native fetch with undici ProxyAgent import { ProxyAgent, fetch as undiciFetch } from 'undici';

const proxyAgent = new ProxyAgent( 'http://user:pass@gate.hexproxies.com:8080' ); const res = await undiciFetch('https://httpbin.org/ip', { dispatcher: proxyAgent, }); console.log(await res.json()); ```

Agent Reuse and Connection Pooling

A single HttpsProxyAgent instance maintains an internal connection pool. Reuse the same agent across multiple axios requests to avoid repeated TCP handshakes to the proxy gateway. Creating a new agent per request wastes 20-40ms on connection setup each time.

Axios vs Undici vs node-fetch

Axios provides the most familiar API with interceptors, automatic JSON parsing, and request cancellation. Undici is the fastest option with zero dependencies (bundled in Node 18+). node-fetch mirrors the browser Fetch API but requires the separate https-proxy-agent package. Choose based on your existing codebase.

Configuration Options

• **Proxy URL** -- http://user:pass@gate.hexproxies.com:8080 passed to the agent constructor.
• **Timeout** -- Set timeout: 30000 on axios or AbortController with setTimeout for fetch.
• **Keep-Alive** -- The agent enables keep-alive by default. Set keepAlive: false only if you need a fresh connection per request.
• **Max Sockets** -- Defaults to Infinity. Set maxSockets: 50 on the agent to limit concurrent proxy connections.
• **TLS Options** -- Pass rejectUnauthorized: true (default) in the agent options. Never disable TLS verification in production.

Error Handling

Node.js proxy errors surface as specific error codes that require distinct handling strategies.

1. ECONNREFUSED
2. - The proxy gateway rejected the connection or is unreachable
3. - Verify gate.hexproxies.com:8080 resolves and is not blocked by a firewall
4. - Check if your IP is whitelisted on the Hex Proxies dashboard

2. ETIMEDOUT / ESOCKETTIMEDOUT - Connection to the proxy or destination timed out - Increase axios timeout from 30000 to 60000 for slow destinations - Implement retry with axios-retry or custom interceptor

3. HPE_INVALID_CONSTANT (Parse Error) - The proxy returned a malformed HTTP response - Usually caused by the destination sending non-HTTP content - Add response validation before parsing

4. 407 Proxy Authentication Required - Credentials in the agent URL are incorrect - Ensure username and password are URL-encoded for special characters - Verify subscription status on the Hex Proxies dashboard

5. ECONNRESET - The proxy or destination closed the connection unexpectedly - Retry with a new agent instance to get a fresh connection - For persistent resets, switch to a different proxy pool region ```

Use axios interceptors or try/catch with async/await to handle errors consistently across your application.