ProxyHttpAgent

1.0.1 verified Sat Apr 25 auth: no javascript

ProxyHttpAgent (v1.0.1) is a factory for creating HTTP proxy agents supporting https→(http, https) and http→(http, https) tunneling, built on top of the node-tunnel module. It allows you to easily use proxies with http/https modules or node-fetch, with flexible proxy configuration via URL or object. Published as TypeScript-first with built-in type definitions, it exports `getProxyHttpAgent` along with `HttpsAgent` and `HttpAgent` types. Released in 2025, it is currently at stable v1. It differentiates by offering a simple API for creating agents that support both secure and insecure proxy connections with minimal boilerplate.

Common errors

error Error: getaddrinfo ENOTFOUND proxy.example.com ↓

cause Proxy hostname not resolvable or network issue.

fix

Check proxy URL and network connectivity.

error TypeError: agent is not a function ↓

cause Incorrect import: importing `getProxyHttpAgent` as a function when not imported correctly.

fix

Use import { getProxyHttpAgent } from 'proxy-http-agent' instead of import getProxyHttpAgent from 'proxy-http-agent'.

Warnings

gotcha Options object may override agent settings; ensure `agent` is set correctly. ↓

fix Use `opts.agent = agent` after parsing URL, and delete any existing `port` to avoid conflicts.

deprecated The npm package name 'proxy-http-agent' may be confused with other similarly named packages. Always verify the correct package. ↓

fix Double-check package name in package.json.

gotcha When using string proxy URL, ensure protocol is specified (http:// or https://). ↓

fix Always include the protocol in the proxy URL, e.g., 'http://proxy.example.com:8080'.

Install

npm install proxy-http-agent

yarn add proxy-http-agent

pnpm add proxy-http-agent

Imports

getProxyHttpAgent

wrong

const getProxyHttpAgent = require('proxy-http-agent')

correct

import { getProxyHttpAgent } from 'proxy-http-agent'

ESM import is preferred; the package provides TypeScript types.

HttpsAgent
```
import { HttpsAgent } from 'proxy-http-agent'
```
TypeScript type for the returned https.Agent instance.
HttpAgent
```
import { HttpAgent } from 'proxy-http-agent'
```
TypeScript type for the returned http.Agent instance.

Quickstart

Creating a proxy agent with proxy URL from environment and using it with https.get.

import { getProxyHttpAgent } from 'proxy-http-agent';
import https from 'https';

const proxyUrl = process.env.HTTP_PROXY ?? 'http://localhost:3128';
const agent = getProxyHttpAgent({
  proxy: proxyUrl,
  rejectUnauthorized: false
});

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  agent
};

https.get(options, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => console.log(data));
}).on('error', (err) => console.error(err));