Node.js HTTP/WebSocket Programmable Proxy

Common errors

• Error: Must provide a target protocol and host (e.g. http://localhost)

  cause The `target` option in the `createProxyServer` constructor or `proxy.web`/`proxy.ws` calls is either missing or malformed.
  fix Ensure 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

  cause 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()`.
  fix First, 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

  cause 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.
  fix Verify 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.

Warnings

• breaking Major breaking changes were introduced after the 0.8.x series. Direct migration from these older versions to 1.x.x without consulting the `UPGRADING.md` guide will likely result in compatibility issues.
  Fix: Refer to the `UPGRADING.md` document linked in the package's README for detailed migration steps when upgrading from pre-1.0.0 versions.
• gotcha Proxy errors must be explicitly handled, either by listening to the `error` event on the proxy instance or by providing an error callback to `proxy.web` or `proxy.ws` calls. Unhandled errors can lead to ungraceful server shutdowns or unresponsiveness.
  Fix: Implement `proxy.on('error', (err, req, res) => { /* handle error */ });` or ensure an error callback is passed to proxy methods like `proxy.web(req, res, options, (err) => { /* handle error */ });`.
• gotcha The `target` option is mandatory for `proxy.web` and `proxy.ws` calls, specifying the destination URL for the proxied request. Omitting or providing an invalid target will result in connection errors and prevent successful proxying.
  Fix: Always ensure `target` is correctly specified in the options object, e.g., `{ target: 'http://localhost:8080' }`, or passed directly to the `web`/`ws` methods.

Install

• npm install http-proxy npm
• yarn add http-proxy yarn
• pnpm add http-proxy pnpm

Imports

• httpProxy (Module Object, CommonJS)
  wrong:

  import httpProxy from 'http-proxy';

  correct:

  const httpProxy = require('http-proxy');

  This imports the entire CommonJS module object, which contains the `createProxyServer` factory function as a property.
• httpProxy (Module Object, ESM)
  wrong:

  const httpProxy = require('http-proxy');

  correct:

  import httpProxy from '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)
  wrong:

  const createProxyServer = require('http-proxy').createProxyServer;

  correct:

  const { createProxyServer } = require('http-proxy');

  This directly destructures the `createProxyServer` function from the CommonJS module object for convenience.
• createProxyServer (Factory Function, ESM Named Import)
  wrong:

  import createProxyServer from 'http-proxy';

  correct:

  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;`.

Quickstart

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);
});