HTTP Proxy Agent

9.0.0 · active · verified Tue Apr 21

`http-proxy-agent` provides a robust `http.Agent` implementation designed for making HTTP requests through an HTTP or HTTPS proxy server in Node.js environments. Currently at version 9.0.0, this library is part of the actively maintained `proxy-agents` monorepo, which generally sees updates aligned with Node.js LTS releases. Its primary function is to integrate seamlessly with Node's built-in `http` module, abstracting the proxy connection details. A key distinction is its specific focus on `http` module requests; for proxying `https` module requests, the companion `https-proxy-agent` package should be used. It supports standard `http.Agent` options and allows for custom headers to be sent to the proxy. This package is specifically designed for Node.js environments, requiring Node.js 20 or later for version 9.0.0.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `http-proxy-agent` in a CommonJS module context, as the package is now primarily designed for ES Modules.

fix Convert your project or relevant files to use ES Modules (`'type': 'module'` in `package.json` and `.mjs` files), or use dynamic `import()` if loading from a CJS module (`const { HttpProxyAgent } = await import('http-proxy-agent');`).
```
Error: This module requires Node.js >= 20
```
cause The application is being executed on a Node.js runtime version older than 20, which does not meet the minimum requirement for `http-proxy-agent` v9.0.0.

fix Update your Node.js development and deployment environments to version 20 or newer.
```
connect ECONNREFUSED <proxy_ip>:<proxy_port>
```
cause The proxy server specified in the `HttpProxyAgent` URL is unreachable, not running, or actively refusing connections from your application.

fix Verify that the proxy server's IP address and port are correct, ensure the proxy service is running and accessible from your network, and check for any local or network firewall rules that might be blocking the connection.

Warnings

breaking The minimum Node.js version required for `http-proxy-agent` v9.0.0 and subsequent releases has been raised to Node.js 20. Running on older Node.js versions will result in runtime errors.
Fix: Upgrade your Node.js runtime environment to version 20 or newer to ensure compatibility and stability.
gotcha This `HttpProxyAgent` is specifically designed for proxying HTTP requests made using Node.js's `http` module. If you need to proxy HTTPS requests made with the `https` module (e.g., `https.get`), you must use the companion `https-proxy-agent` package instead.
Fix: For HTTPS requests, switch to using `import { HttpsProxyAgent } from 'https-proxy-agent';`.
gotcha Custom headers provided in the `options.headers` object for the proxy agent may not be stripped by the proxy server and could be forwarded to the final destination server. This could lead to unintended information leakage or unexpected behavior.
Fix: Exercise caution when setting custom headers. Only include headers explicitly intended for the proxy or those you are comfortable being sent to the final destination endpoint.

Install

npm install http-proxy-agent npm
yarn add http-proxy-agent yarn
pnpm add http-proxy-agent pnpm

Imports

HttpProxyAgent
wrong:
```
const HttpProxyAgent = require('http-proxy-agent').HttpProxyAgent;
```
correct:
```
import { HttpProxyAgent } from 'http-proxy-agent';
```
This package is ESM-first since v9. While CommonJS `require` might work via transpilation or bundlers, direct CJS usage is discouraged and may lead to issues.
HttpProxyAgentOptions
```
import type { HttpProxyAgentOptions } from 'http-proxy-agent';
```
Import types separately when only needing the type definition for static analysis.

default

wrong:

import HttpProxyAgent from 'http-proxy-agent';

correct:

import { HttpProxyAgent } from 'http-proxy-agent';

The primary class `HttpProxyAgent` is a named export, not a default export.

Quickstart

Demonstrates how to create and use an `HttpProxyAgent` instance with Node.js's built-in `http.get` method to route an HTTP request through a specified proxy server.

import * as http from 'http';
import { HttpProxyAgent } from 'http-proxy-agent';

// Replace with your actual proxy URL and target URL
const proxyUrl = process.env.HTTP_PROXY_URL ?? 'http://127.0.0.1:3128';
const targetUrl = process.env.TARGET_URL ?? 'http://example.com/api/';

const agent = new HttpProxyAgent(proxyUrl);

http.get(targetUrl, { agent }, (res) => {
  console.log(`Proxying request to ${targetUrl} via ${proxyUrl}`);
  console.log('Response status:', res.statusCode);
  console.log('Response headers:', res.headers);
  // Log a portion of the response body to show it's working
  res.on('data', (chunk) => {
    process.stdout.write(chunk.toString().substring(0, 100) + '...');
  });
  res.on('end', () => {
    console.log('\n--- Request complete ---');
  });
}).on('error', (err) => {
  console.error('Request failed:', err.message);
});

view raw JSON →