Registry / http-networking / http-proxy-agent

http-proxy-agent

library9.0.0jsnpmunverified

`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.

http-networking web-framework

npm install http-proxy-agent

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-PROXY-AGENT

http-proxy-agent

http-networkingjavascriptv9.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpProxyAgent

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

✗ const HttpProxyAgent = require('http-proxy-agent').HttpProxyAgent;

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

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

✗ import HttpProxyAgent from 'http-proxy-agent';

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

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); });

Debug

Known issues

breakingThe 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.

affects: >=9.0.0

gotchaThis `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';`.

affects: >=1.0.0

gotchaCustom 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.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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>

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.

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

agent-baserequiredCore abstraction for creating custom `http.Agent` implementations, managing common agent functionalities.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/TooTallNate/proxy-agents ↗

packagehttps://www.npmjs.com/package/http-proxy-agent ↗