{"id":16508,"library":"proxy","title":"Node.js HTTP Proxy Server","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/TooTallNate/proxy-agents","tags":["javascript","http","https","proxy","connect","tunnel","squid","privoxy","apache"],"install":[{"cmd":"npm install proxy","lang":"bash","label":"npm"},{"cmd":"yarn add proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add proxy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { createProxy } = require('proxy');","symbol":"createProxy","correct":"import { createProxy } from 'proxy';"},{"note":"The `http` module from Node.js is commonly imported alongside `proxy` to create the underlying server instance.","symbol":"http","correct":"import * as http from 'http';"},{"note":"For TypeScript users, type definitions can be imported for better autocompletion and type checking, especially for the `ProxyServer` instance returned by `createProxy`.","symbol":"ProxyServer","correct":"import { ProxyServer } from 'proxy/dist/types';"}],"quickstart":{"code":"import * as http from 'http';\nimport { createProxy } from 'proxy';\n\nconst server = createProxy(http.createServer());\n\n// Basic authorization example (replace with real auth for production)\nserver.authenticate = function (req, fn) {\n  const auth = req.headers['proxy-authorization'];\n  if (auth && auth.startsWith('Basic ')) {\n    const credentials = Buffer.from(auth.slice(6), 'base64').toString().split(':');\n    const [username, password] = credentials;\n    if (username === 'user' && password === 'password') {\n      return fn(null, true);\n    }\n  }\n  fn(null, false);\n};\n\nserver.listen(3128, () => {\n  const address = server.address();\n  const port = typeof address === 'string' ? address : address?.port;\n  console.log('HTTP(s) proxy server listening on port %d', port);\n});","lang":"typescript","description":"This example sets up a basic HTTP(S) proxy server on port 3128 with a simple username/password authentication scheme using the `createProxy` API."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer. Use a tool like `nvm` or `volta` to manage Node.js versions.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Using 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` the `proxy` package in a CommonJS module when the package is primarily designed as an ES Module since v4.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/proxy/index.js from ... not supported."},{"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.","cause":"Another process is already listening on the port (default 3128) that the proxy server is trying to bind to.","error":"Error: listen EADDRINUSE: address already in use :::3128"},{"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>`).","cause":"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.","error":"HTTP/1.1 407 Proxy Authentication Required"}],"ecosystem":"npm"}