Registry / http-networking / http-proxy-3

http-proxy-3

JSON →
library1.23.2jsnpmunverified

http-proxy-3 is an actively maintained, modern rewrite of the popular `http-proxy` library for Node.js, currently at version 1.23.2. It provides programmable HTTP/HTTPS and WebSocket proxying capabilities, suitable for building reverse proxies, load balancers, or API gateways. Key differentiators include a complete rewrite in TypeScript for enhanced type safety and maintainability, full HTTP/2 support via the `fetch` API, and comprehensive updates to all dependent packages to address security vulnerabilities. The library explicitly fixes known socket leaks and uncatchable WebSocket errors present in the unmaintained original `http-proxy`. It is used in production by major projects like Vite, CoCalc, and JupyterHub, ensuring a stable and reliable solution for integrating application logic with proxy server functionality.

npm install http-proxy-3
INSTALL
IMPORT
SIG · HTTP-PROXY-3
H
http-proxy-3
http-networkingjavascriptv1.23.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createProxyServer
import { createProxyServer } from 'http-proxy-3';
const httpProxy = require('http-proxy-3'); const proxy = httpProxy.createProxyServer();
http-proxy-3 is primarily designed for ES Modules, though CommonJS `require` might work with transpilation or specific Node.js loader configurations. `createProxyServer` is the main factory function.
ProxyServerOptions
import type { ProxyServerOptions } from 'http-proxy-3';
This type definition is crucial for TypeScript users to correctly configure the proxy server instance.
ProxyServer
import type { ProxyServer } from 'http-proxy-3';
Represents the instance returned by `createProxyServer`, useful for type annotations when working with proxy event listeners or methods like `web()` and `ws()`.

This quickstart sets up a basic HTTP and WebSocket proxy that forwards requests from port 8000 to a target server running on port 9000, demonstrating core proxying functionality and error handling.

import * as http from 'node:http'; import { createProxyServer, type ProxyServerOptions } from 'http-proxy-3'; // Create a target HTTP server const targetServer = http.createServer((req, res) => { console.log(`Target received: ${req.method} ${req.url}`); res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello from the target server!'); }); targetServer.listen(9000, () => { console.log('Target server listening on http://localhost:9000'); }); // Create a basic HTTP proxy server const proxyOptions: ProxyServerOptions = { target: 'http://localhost:9000', ws: true // Enable websocket proxying }; const proxy = createProxyServer(proxyOptions); // Handle proxy errors proxy.on('error', (err, req, res) => { console.error('Proxy Error:', err); if (res && res.writeHead) { res.writeHead(500, { 'Content-Type': 'text/plain' }); res.end('Something went wrong with the proxy.'); } }); // Create a proxy listening server const proxyServer = http.createServer((req, res) => { console.log(`Proxying request: ${req.method} ${req.url}`); proxy.web(req, res); }); proxyServer.on('upgrade', (req, socket, head) => { console.log(`Proxying websocket upgrade: ${req.url}`); proxy.ws(req, socket, head); }); proxyServer.listen(8000, () => { console.log('Proxy server listening on http://localhost:8000'); console.log('Test with: curl http://localhost:8000'); console.log('Test websockets with a client connecting to ws://localhost:8000'); });
Debug
Known issues
breakinghttp-proxy-3 requires Node.js version 18 or higher. Applications running on older Node.js runtimes must upgrade their environment before adopting this package.
fix
Upgrade Node.js to version 18 or newer.
affects: <1.23.0
breakingThis library is a complete rewrite of `http-proxy`, addressing many longstanding issues including socket leaks and uncatchable WebSocket errors in the original package. While API compatible, direct migration from `http-proxy` may expose subtle behavioral changes or require updating code that relied on deprecated/insecure APIs (e.g., `URL` instead of `parse`).
fix
Thoroughly test existing proxy configurations after upgrading from `http-proxy`. Review and update any custom request/response handling logic that might rely on older Node.js or `http-proxy` internals.
affects: >=1.0.0
gotchaThe README notes that using the proxy server introduces a performance penalty, with proxied operations potentially taking 'about twice as long' compared to direct connections. This should be considered for highly performance-sensitive applications.
fix
Benchmark your application's specific use case to determine the impact. Optimize backend services or consider alternative architectures if the performance overhead is unacceptable.
affects: >=1.0.0
gotchaHTTP/2 support in http-proxy-3 is achieved via the `fetch` API and is currently marked as 'experimental'. While functional and tested, the API and behavior may change in future versions.
fix
Use HTTP/2 features with caution in production environments. Monitor release notes for changes related to HTTP/2 support and be prepared to adapt configurations as the feature matures.
affects: >=1.0.0
breakinghttp-proxy-3 fixes a significant security vulnerability (related to issue #1647 in the original http-party/node-http-proxy). Using older, unmaintained versions of `http-proxy` exposes applications to this vulnerability.
fix
Immediately upgrade to http-proxy-3 to benefit from this and other security patches.
affects: <1.0.0 (for http-proxy-3); all versions of unpatched http-proxy
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::8000
The port the proxy server is trying to listen on is already in use by another process.
fix
Change the proxy's listening port to an available one, or stop the process currently using the port (e.g., `kill -9 <PID>` on Linux/macOS or `netstat -ano | findstr :<PORT>` followed by `taskkill /PID <PID> /F` on Windows).
Error: connect ECONNREFUSED 127.0.0.1:9000
The proxy server could not connect to the target server because the target server is not running or its address/port is incorrect.
fix
Ensure the target server is running and accessible at the configured `target` address and port. Verify no firewalls are blocking the connection between the proxy and target.
Proxy Error: Could not proxy request /socket.io/?EIO=3&transport=websocket to ws://localhost:9000/socket.io/?EIO=3&transport=websocket (ECONNREFUSED)
The proxy failed to establish a WebSocket connection to the target server, often because the target does not support WebSockets or the WebSocket server isn't running.
fix
Confirm that the target server correctly implements and listens for WebSocket connections. Ensure `ws: true` is set in the `createProxyServer` options if you intend to proxy WebSockets.
HTTP/1.1 407 Proxy Authentication Required
The proxy itself (or an upstream proxy) requires authentication before it will forward the request.
fix
Provide the necessary authentication credentials in the proxy configuration if `http-proxy-3` is acting as a client to another authenticated proxy, or ensure your client accessing `http-proxy-3` provides valid credentials if `http-proxy-3` is configured to require them.
Error: Parse Error: HPE_INVALID_HEADER_TOKEN
The target server returned a malformed HTTP header, which Node.js's HTTP parser cannot interpret.
fix
Inspect the responses from your target server for invalid characters or formatting in HTTP headers. This often indicates an issue with the target server's HTTP implementation.
Upgrade
Version history
1.23.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources