http-proxy is a robust and programmable HTTP proxying library for Node.js, designed to facilitate the creation of components such as reverse proxies and load balancers. It offers comprehensive support for both HTTP(S) and WebSockets. The current stable version is 1.18.1. While its release cadence is not rapid, the project undergoes periodic maintenance, as highlighted by the 1.17.0 release which delivered numerous bug fixes and feature additions, indicating active, albeit slower, development. A key differentiator is its `createProxyServer` factory, which returns a flexible proxy instance, allowing developers to customize request and response pipelines for fine-grained control over proxied traffic, making it suitable for complex proxying scenarios beyond basic URL forwarding.
Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This imports the entire CommonJS module object, which contains the `createProxyServer` factory function as a property.
const httpProxy = require('http-proxy');
For ESM, the CommonJS module is typically imported as a default export. The `createProxyServer` function is then accessed as `httpProxy.createProxyServer`.
import httpProxy from 'http-proxy';
This directly destructures the `createProxyServer` function from the CommonJS module object for convenience.
const { createProxyServer } = require('http-proxy');
This assumes `http-proxy` provides a named export for `createProxyServer` for direct ESM access. If not, use `import httpProxy from 'http-proxy'; const { createProxyServer } = httpProxy;`.
import { createProxyServer } from 'http-proxy';
This example sets up a basic `http-proxy` server on port 8000 that forwards both HTTP and WebSocket requests to a target server running on port 9000. It includes basic error handling and logging.
const http = require('http');
const httpProxy = require('http-proxy');
// --- Target Server ---
const targetPort = 9000;
const targetServer = http.createServer((req, res) => {
console.log(`[Target] Received request for: ${req.url}`);
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end(`Hello from Target Server! You requested ${req.url}\n`);
});
targetServer.listen(targetPort, () => {
console.log(`[Target] Server listening on http://localhost:${targetPort}`);
});
// --- Proxy Server ---
const proxyPort = 8000;
const proxy = httpProxy.createProxyServer({
target: `http://localhost:${targetPort}`,
ws: true // Enable WebSocket proxying
});
proxy.on('error', (err, req, res) => {
console.error('[Proxy] HTTP error:', err.message);
if (!res.headersSent) {
res.writeHead(500, { 'Content-Type': 'text/plain' });
res.end('Proxy Error: Could not reach the target.');
}
});
proxy.on('proxyReq', (proxyReq, req, res, options) => {
console.log(`[Proxy] Proxying HTTP request: ${req.method} ${req.url}`);
});
proxy.on('proxyRes', (proxyRes, req, res) => {
console.log(`[Proxy] Response from target: ${proxyRes.statusCode}`);
});
const proxyServer = http.createServer((req, res) => {
// Handle regular HTTP(S) requests
proxy.web(req, res);
});
proxyServer.on('upgrade', (req, socket, head) => {
// Handle WebSocket upgrade requests
console.log(`[Proxy] Proxying WebSocket upgrade for: ${req.url}`);
proxy.ws(req, socket, head);
});
proxyServer.listen(proxyPort, () => {
console.log(`[Proxy] Server listening on http://localhost:${proxyPort}`);
console.log(`
Test HTTP by visiting: http://localhost:${proxyPort}/any/path`);
console.log(`Test WebSocket (e.g., with 'wscat'): wscat -c ws://localhost:${proxyPort}`);
});
// Clean up on exit
process.on('SIGINT', () => {
console.log('\n[App] Shutting down servers...');
proxyServer.close(() => console.log('[Proxy] Server closed.'));
targetServer.close(() => console.log('[Target] Server closed.'));
process.exit(0);
});
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.
Agent activity
0 hits · last 30 days
No traffic data recorded yet.