Registry / http-networking / https-proxy-agent

https-proxy-agent

library9.0.0jsnpmunverified

https-proxy-agent is an `http.Agent` implementation specifically designed for making HTTPS requests through an HTTP or HTTPS proxy server. It leverages the HTTP `CONNECT` method to establish a TCP tunnel through the proxy to the target destination. This enables secure communication over proxied networks and is also compatible with protocols like WebSockets that utilize the `CONNECT` method for proxy tunneling. The current stable version is 9.0.0, released as part of the `proxy-agents` monorepo, which implies a release cadence tied to updates across the proxy agent family. A key differentiator is its direct focus on the `CONNECT` method for HTTPS and WebSocket tunneling, providing a robust solution for environments requiring explicit proxy configuration. It requires Node.js version 20 or higher.

http-networking

npm install https-proxy-agent

github ↗package ↗

INSTALL

IMPORT

SIG · HTTPS-PROXY-AGENT

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

HttpsProxyAgent

✓ import { HttpsProxyAgent } from 'https-proxy-agent';

✗ const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;

The package is primarily designed for ESM usage since v9.0.0. While CommonJS might work with transpilers, direct `require` can be problematic due to how `exports` are configured. Use named import from the package root.

HttpsProxyAgentOptions

✓ import type { HttpsProxyAgentOptions } from 'https-proxy-agent';

✗ import { HttpsProxyAgentOptions } from 'https-proxy-agent';

When importing types for TypeScript, use `import type` to ensure they are stripped during compilation.

This quickstart demonstrates how to configure and use `HttpsProxyAgent` with Node.js's built-in `https` module to route requests through a specified HTTP(s) proxy server.

import * as https from 'https'; import { HttpsProxyAgent } from 'https-proxy-agent'; const PROXY_URL = process.env.HTTPS_PROXY ?? 'http://168.63.76.32:3128'; // Example proxy, replace with a real one const TARGET_URL = 'https://example.com'; console.log(`Attempting to fetch ${TARGET_URL} via proxy ${PROXY_URL}`); const agent = new HttpsProxyAgent(PROXY_URL, { headers: { 'X-Custom-Proxy-Header': 'MyValue' } }); https.get(TARGET_URL, { agent }, (res) => { console.log(`Status Code: ${res.statusCode}`); console.log('Response Headers:', res.headers); let data = ''; res.on('data', (chunk) => { data += chunk; }); res.on('end', () => { console.log('Response Body Snippet:', data.substring(0, 200) + '...'); }); }).on('error', (err) => { console.error('Error fetching URL:', err.message); });

Debug

Known issues

breakingVersion 9.0.0 and above now require Node.js version 20 or higher. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 20 or newer. If you cannot upgrade, use a previous major version of `https-proxy-agent` (e.g., `^8.0.0`).

affects: >=9.0.0

gotchaWhen migrating from older versions or CommonJS, ensure you use ESM `import` syntax as the package's `package.json` `exports` field prioritizes ESM, potentially causing issues with `require()`.

fix

Use `import { HttpsProxyAgent } from 'https-proxy-agent';` instead of `const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;` in your JavaScript/TypeScript files.

affects: >=9.0.0

gotchaThe `proxy` argument to `HttpsProxyAgent` expects a URL string or `URL` object. Incorrectly formatted URLs or missing protocol can lead to connection errors.

fix

Ensure the proxy URL is a valid string (e.g., 'http://proxy.example.com:8080' or 'https://secureproxy.com') or a `URL` object. Always include the protocol (http/https).

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES module .../node_modules/https-proxy-agent/dist/index.mjs from .../my-app.js not supported.

Attempting to use `require()` to import `https-proxy-agent` when your project is configured for CommonJS, but the package is primarily ESM.

fix

Convert your project to use ES Modules, or if that's not feasible, ensure your tooling (e.g., Webpack, Rollup) correctly handles ESM modules in a CommonJS context. The recommended fix is to use `import { HttpsProxyAgent } from 'https-proxy-agent';` and ensure your project's `type` is set to `module` in `package.json` or use an `.mjs` extension for your file.

Error: read ECONNRESET

This error often indicates that the proxy server closed the connection unexpectedly, possibly due to invalid credentials, incorrect proxy configuration, or network issues between your application and the proxy.

fix

Double-check your proxy URL, port, and any required authentication. Verify network connectivity to the proxy server. The proxy might also be blocking the target URL.

Upgrade

Version history

9.0.0latest on npm

Audit

Dependencies

agent-baserequiredCore abstract agent implementation extended by HttpsProxyAgent.

Agent activity

8 hits · last 30 days

node

Resources

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

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