proxy

library0.0.1jsnpmunverified

The `proxy` package provides a programmatic HTTP(S) proxy server API for Node.js, allowing developers to script custom proxy logic. Its current stable version is `4.0.0`, which notably raised the minimum Node.js requirement to version 20. The project maintains an active release cadence, with recent updates across its associated `proxy-agent` ecosystem, ensuring compatibility and improvements. Key differentiators include its simple `createProxy` API for building custom proxy servers, similar to established solutions like Squid or Privoxy, but integrated directly within a Node.js environment. It supports both standard HTTP proxying and the HTTP `CONNECT` method for tunneling. The package also includes a companion CLI tool for quick server spawning.

http-networking web-framework

npm install proxy

github ↗package ↗

INSTALL

IMPORT

SIG · PROXY

proxy

http-networkingjavascriptv0.0.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.

createProxy

✓ import { createProxy } from 'proxy';

✗ const { createProxy } = require('proxy');

Since v4.0.0, the package primarily targets ESM environments aligned with Node.js >=20. While CJS might still function via compatibility layers, ESM is the idiomatic approach.

http

✓ import * as http from 'http';

The `http` module from Node.js is commonly imported alongside `proxy` to create the underlying server instance.

ProxyServer

✓ import { ProxyServer } from 'proxy/dist/types';

For TypeScript users, type definitions can be imported for better autocompletion and type checking, especially for the `ProxyServer` instance returned by `createProxy`.

This example sets up a basic HTTP(S) proxy server on port 3128 with a simple username/password authentication scheme using the `createProxy` API.

import * as http from 'http'; import { createProxy } from 'proxy'; const server = createProxy(http.createServer()); // Basic authorization example (replace with real auth for production) server.authenticate = function (req, fn) { const auth = req.headers['proxy-authorization']; if (auth && auth.startsWith('Basic ')) { const credentials = Buffer.from(auth.slice(6), 'base64').toString().split(':'); const [username, password] = credentials; if (username === 'user' && password === 'password') { return fn(null, true); } } fn(null, false); }; server.listen(3128, () => { const address = server.address(); const port = typeof address === 'string' ? address : address?.port; console.log('HTTP(s) proxy server listening on port %d', port); });

proxy --version

Debug

Known issues

breakingVersion 4.0.0 of `proxy` and its related packages (e.g., `socks-proxy-agent`) 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. Use a tool like `nvm` or `volta` to manage Node.js versions.

affects: >=4.0.0

breakingThe `package.json` exports have been simplified in v4.0.0, removing 'unnecessary imports restriction'. This change, while intended to streamline module resolution, might affect how some bundlers or CJS environments consume the package. ESM is the primary target.

fix

Ensure your project is configured for ESM imports where possible (`'type': 'module'` in `package.json`). If using CommonJS, verify imports work as expected or consider using dynamic `import()` if issues arise.

affects: >=4.0.0

gotchaUsing the CLI's `--authenticate` option with shell commands (e.g., `proxy --authenticate 'if [...] then exit 0'`) introduces potential security risks if not handled carefully. Command injection vulnerabilities could arise if input variables are not properly escaped.

fix

For production environments, implement custom authentication logic programmatically using the `server.authenticate` function, which offers more control and better security practices compared to shell-based authentication.

affects: >=1.0.0

gotchaWhen configuring the proxy with `--local-address` or `localAddress` in the API, the specified IP address must be an available local network interface. Incorrectly configured addresses will prevent the proxy from binding or forwarding requests.

fix

Verify the specified `localAddress` IP is valid and available on the host machine. Use `ipconfig` (Windows) or `ifconfig`/`ip addr` (Linux/macOS) to check network interfaces.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/proxy/index.js from ... not supported.

Attempting to `require()` the `proxy` package in a CommonJS module when the package is primarily designed as an ES Module since v4.0.0.

fix

Change your import statement to `import { createProxy } from 'proxy';` and ensure your `package.json` has `'type': 'module'` or use a file extension like `.mjs` for your module.

Error: listen EADDRINUSE: address already in use :::3128

Another process is already listening on the port (default 3128) that the proxy server is trying to bind to.

fix

Either stop the conflicting process or configure the proxy server to listen on a different port using `server.listen(PORT)` in the API or the `-p`/`--port` option with the CLI tool.

HTTP/1.1 407 Proxy Authentication Required

The proxy server is configured to require authentication (e.g., via `server.authenticate` or the CLI's `--authenticate` option), but the client request did not provide valid `Proxy-Authorization` headers.

fix

Ensure the client sending requests through the proxy provides a correctly formatted `Proxy-Authorization` header with valid credentials (e.g., `Proxy-Authorization: Basic <base64_encoded_username:password>`).

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

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

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