Node.js HTTP Proxy (Node 16+ fork)

Common errors

• connect ECONNREFUSED 127.0.0.1:9000

  cause The target server configured for the proxy (e.g., `http://localhost:9000`) is not running or not accessible.
  fix Ensure the target server process is started and listening on the specified host and port before the proxy attempts to forward requests to it. Check firewall rules if the target is remote.

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

  cause The `target` option required by `createProxyServer` or `proxy.web`/`proxy.ws` methods was either missing or malformed.
  fix Provide a complete target URL string including protocol, host, and port (e.g., `{ target: 'http://localhost:3000' }`) in the proxy options.

• Error: target server should listen on event 'upgrade' or be created by http.createServer.listen(port) with a 'ws' event.

  cause Attempted to proxy a WebSocket connection (`proxy.ws`) to a target server that does not handle WebSocket `upgrade` requests, or the target server's WebSocket handling is improperly configured.
  fix Ensure the target server is capable of handling WebSocket connections and has an `upgrade` event listener or uses a library (like `ws` or `socket.io`) that manages WebSocket upgrades correctly.

Warnings

• breaking This package is a fork specifically designed for Node.js v16.x and later. While its `engines` field might indicate broader compatibility, using it on significantly older Node.js versions (e.g., < v14) may lead to unexpected behavior, compatibility issues, or even crashes due to underlying API changes or deprecations it aims to address for modern Node.js.
  Fix: Ensure your Node.js environment is at least v16.x for guaranteed compatibility and stability with this fork.
• gotcha Failing to handle `error` events emitted by the `ProxyServer` instance can cause your Node.js application to crash silently or with an unhandled promise rejection/exception. Errors can occur due to target server unavailability, network issues, or misconfigurations.
  Fix: Always attach an error handler using `proxy.on('error', (err, req, res) => { ... })` or by providing an error callback to `proxy.web(req, res, options, (err) => { ... })` to gracefully manage proxying failures.
• gotcha As a fork, `http-proxy-node16` may not always be perfectly in sync with the latest features, bug fixes, or security patches released in the original `node-http-proxy` upstream project. Users should periodically check both projects for critical updates and potential divergences.
  Fix: Monitor the GitHub repositories of both `http-proxy-node16` and `node-http-proxy` to stay informed about updates and assess which project best meets your security and feature requirements.
• gotcha The `proxy.listen(port)` method is a convenience wrapper for `http.createServer`. For more control over the underlying HTTP server's lifecycle, request handling, or to integrate with existing `http.Server` instances, it is generally recommended to create your own `http.createServer` and use `proxy.web(req, res, options)` or `proxy.ws(req, socket, head, options)` within its request listeners.
  Fix: Instead of `proxy.listen(8000)`, consider `const server = http.createServer((req, res) => proxy.web(req, res, { target: '...' })); server.listen(8000);` for greater control.

Install

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

Imports

• createProxyServer
  wrong:

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

  correct:

  import { createProxyServer } from 'http-proxy-node16';

  The primary factory function for creating a proxy instance. Supports both CommonJS (using destructuring `const { createProxyServer } = require(...)`) and ESM import styles.
• ProxyServer

  import type { ProxyServer } from 'http-proxy-node16';

  TypeScript interface for the proxy instance returned by `createProxyServer()`, providing methods like `web`, `ws`, `listen`, and `close`.
• ProxyServerOptions
  wrong:

  import { ProxyServerOptions } from 'http-proxy-node16';

  correct:

  import type { ProxyServerOptions } from 'http-proxy-node16';

  TypeScript interface for the configuration object passed to `createProxyServer()`. Only use with `type` import for static type checking.
• Full module object (CommonJS)

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

  CommonJS import of the entire module object, from which `httpProxy.createProxyServer` can then be accessed, mimicking older `node-http-proxy` patterns.

Quickstart

Sets up a basic stand-alone proxy server on port 8000 that forwards all HTTP requests to a target server running on port 9000, demonstrating core proxying functionality and basic error handling.

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

// Create your proxy server and set the target in the options.
// It will listen on port 8000 and proxy requests to the target server on 9000.
const proxy = httpProxy.createProxyServer({ target: 'http://localhost:9000' });
proxy.listen(8000);

// Handle errors from the proxy server, essential for robust applications.
proxy.on('error', function (err, req, res) {
  console.error('Proxy error:', err);
  res.writeHead(500, { 'Content-Type': 'text/plain' });
  res.end('Something went wrong with the proxy.');
});

// Create your target server.
http.createServer(function (req, res) {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.write('Request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2));
  res.end();
}).listen(9000);

console.log('Proxy server listening on http://localhost:8000');
console.log('Target server listening on http://localhost:9000');
console.log('Try visiting http://localhost:8000 in your browser to see the proxy in action.');