Registry / http-networking / proxy-chain

proxy-chain

library2.7.1jsnpmunverified

proxy-chain is a Node.js library that provides a programmable HTTP/SOCKS proxy server with extensive features. It supports SSL/TLS, authentication, upstream proxy chaining, and protocol tunneling, enabling dynamic and custom configurations. Key differentiators include its utility for headless browsers like Puppeteer and Playwright, which struggle with authenticated proxy URLs, by providing a local proxy that handles authentication. The library also offers traffic statistics and custom HTTP response capabilities. Developed by Apify, it's a core component in their web scraping platform and is used by Crawlee. The current stable version is 2.7.1, with minor and patch releases occurring frequently, typically on a monthly basis.

http-networking

npm install proxy-chain

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROXY-CHAIN

proxy-chain

http-networkingjavascriptv2.7.1

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.

Server

✓ import { Server } from 'proxy-chain'; // OR (CommonJS) const { Server } = require('proxy-chain');

✗ import ProxyChain from 'proxy-chain'; // No default export // OR (CommonJS, v1 style) const Server = require('proxy-chain'); // In v1, Server was the default export, now it's a named export

The `Server` class is the primary constructor for the proxy server. As of v2.0.0, `proxy-chain` uses named exports. The CommonJS `require('proxy-chain')` now returns an object, so destructuring `{ Server }` or accessing `ProxyChain.Server` is necessary.

anonymizeProxy

✓ import { anonymizeProxy } from 'proxy-chain'; // OR (CommonJS) const { anonymizeProxy } = require('proxy-chain');

The `anonymizeProxy` function is used to create a local proxy that forwards requests to an upstream authenticated proxy, useful for applications that don't support proxy URLs with credentials.

purgeClosedConnections

✓ import { purgeClosedConnections } from 'proxy-chain'; // OR (CommonJS) const { purgeClosedConnections } = require('proxy-chain');

This utility function can be used to explicitly clean up closed connections, helping manage resources in long-running proxy instances.

This quickstart demonstrates how to set up a basic HTTP/HTTPS proxy server that listens on a specified or default port and logs its status. It includes a graceful shutdown handler.

import { Server } from 'proxy-chain'; const PORT = process.env.PROXY_PORT ? parseInt(process.env.PROXY_PORT, 10) : 8000; const server = new Server({ port: PORT, verbose: true, // Optional: add custom authentication logic // An example of a basic authentication handler: // authenticate: ({ username, password }) => { // return username === 'myuser' && password === 'mypassword'; // }, // Optional: add upstream proxy chaining logic // upstreamProxyUrl: 'http://user:pass@upstream.example.com:8080', }); server.listen(() => { console.log(`Proxy server is listening on port ${server.port}`); console.log('Use with: `HTTP_PROXY=http://127.0.0.1:' + server.port + ' curl http://example.com`'); }); process.on('SIGINT', async () => { console.log('Shutting down proxy server...'); await server.close(); console.log('Proxy server closed.'); process.exit(0); });

Debug

Known issues

breakingVersion 2.0.0 introduced breaking changes, most notably switching from a default export to named exports. If you were using `const Server = require('proxy-chain'); new Server()` in v1, you must update to `const { Server } = require('proxy-chain'); new Server()` or `const ProxyChain = require('proxy-chain'); new ProxyChain.Server()` for v2 and later.

fix

Update your import statements to use named exports: `import { Server } from 'proxy-chain';` for ESM or `const { Server } = require('proxy-chain');` for CommonJS. If importing the module object, access the Server class as a property: `const ProxyChain = require('proxy-chain'); new ProxyChain.Server()`.

affects: >=2.0.0

breakingSupport for Node.js versions 9 and lower was dropped in version 2.0.0. The library now requires Node.js 14 or higher.

fix

Upgrade your Node.js runtime environment to version 14 or higher to ensure compatibility. The `engines` field in `package.json` specifies `>=14`.

affects: >=2.0.0

gotchaThe `authentication` handler function expects a specific return object shape: `{ requestAuthentication: boolean, upstreamProxyUrl?: string, failMsg?: string, customTag?: unknown }`. Deviating from this structure, especially in older versions, can lead to unexpected behavior or errors.

fix

Always return an object matching the specified signature from your `authenticate` function. Ensure `requestAuthentication` is a boolean and `upstreamProxyUrl` is a string if an upstream proxy is intended.

affects: >=1.0.0

gotchaThe `proxy-chain` library primarily supports Basic authentication for the `Proxy-Authorization` header. Other authentication schemes are not directly supported.

fix

Ensure your upstream proxies or client configurations use Basic authentication. For more complex schemes, you might need to implement custom logic within the `authenticate` handler or use another proxy layer.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: ProxyChain is not a constructor

Attempting to instantiate the `proxy-chain` module object directly (e.g., `new ProxyChain()`) after `const ProxyChain = require('proxy-chain');`. In v2+, `ProxyChain` is an object containing exports, not the `Server` class itself.

fix

Access the `Server` class from the imported module object using `new ProxyChain.Server()` or destructure it directly with `const { Server } = require('proxy-chain'); new Server()` for CommonJS, or `import { Server } from 'proxy-chain'; new Server()` for ESM.

ERR_REQUIRE_ESM or require() of ES Module ... not supported

Trying to use `require()` to import `proxy-chain` in an ECMAScript Module (ESM) context (e.g., in a file with `"type": "module"` or `.mjs` extension) or vice-versa, without proper configuration or transpilation. Many modern Node.js packages prefer ESM.

fix

For ESM projects, use `import { Server } from 'proxy-chain';`. For CommonJS projects, use `const { Server } = require('proxy-chain');`. Ensure your project's module system is consistently configured.

Error: Invalid upstream proxy URL: '...' (e.g., due to malformed URL or invalid characters)

The `upstreamProxyUrl` provided in the `Server` configuration or returned by the `authenticate` function is not a valid URL or contains unsupported characters (e.g., colon ':' in username).

fix

Validate and ensure that your `upstreamProxyUrl` is a correctly formatted URL. URI-encode username and password components if they contain special characters. Refer to RFC 3986 for URL encoding guidelines.

Upgrade

Version history

2.7.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/apify/proxy-chain ↗

packagehttps://www.npmjs.com/package/proxy-chain ↗

homepagehttps://apify.com ↗