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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
httpProxy (Module Object, CommonJS)
✓ const httpProxy = require('http-proxy');
✗ import httpProxy from 'http-proxy';
This imports the entire CommonJS module object, which contains the `createProxyServer` factory function as a property.
httpProxy (Module Object, ESM)
✓ import httpProxy from 'http-proxy';
✗ 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`.
createProxyServer (Factory Function, CommonJS Destructuring)
✓ const { createProxyServer } = require('http-proxy');
✗ const createProxyServer = require('http-proxy').createProxyServer;
This directly destructures the `createProxyServer` function from the CommonJS module object for convenience.
createProxyServer (Factory Function, ESM Named Import)
✓ import { createProxyServer } from 'http-proxy';
✗ import createProxyServer from '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;`.
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);
});
Errors
Common errors & fixes
Error: Must provide a target protocol and host (e.g. http://localhost)
The `target` option in the `createProxyServer` constructor or `proxy.web`/`proxy.ws` calls is either missing or malformed.
fixEnsure the `target` option is a string with a valid protocol and host (e.g., `'http://localhost:3000'`) or an object specifying `host` and `port`.
TypeError: proxy.web is not a function
This usually means you're trying to call `web` on the `httpProxy` module object itself (e.g., `httpProxy.web(...)`) rather than on an instance created by `httpProxy.createProxyServer()`.
fixFirst, create a proxy instance: `const proxy = httpProxy.createProxyServer(options);`. Then, call `proxy.web(req, res);` on that instance.
Error: connect ECONNREFUSED 127.0.0.1:9000
The target server specified in the `target` option is not running or is inaccessible at the given host and port, preventing `http-proxy` from establishing a connection.
fixVerify that your target server is actively running and listening on the specified host and port. Check firewall rules if the target is on a different machine or network.
Audit
Dependencies
No dependency data recorded yet.