{"id":16382,"library":"http-proxy-node16","title":"Node.js HTTP Proxy (Node 16+ fork)","description":"This package, `http-proxy-node16`, currently at version 1.0.6, is a specialized fork of the popular `node-http-proxy` library. Its primary purpose is to ensure robust compatibility and functionality within Node.js environments version 16.x and later, explicitly addressing potential breaking changes, deprecations, or compatibility issues that might arise when using the original `http-proxy` on newer Node.js runtimes. It offers comprehensive programmable HTTP and WebSocket proxying capabilities, making it an ideal choice for implementing components such as reverse proxies, sophisticated load balancers, or custom HTTP proxy middleware. A key differentiator from the upstream `node-http-proxy` is its explicit focus and testing against Node.js v16 and beyond, providing a reliable solution for applications deployed in these modern environments. The project indicates a maintenance approach welcoming \"bug-fix PRs,\" suggesting a reactive, community-driven cadence for updates. This fork serves as a targeted solution for developers seeking a stable proxying library specifically for their Node.js 16+ applications, where the original project might have broader compatibility concerns or different priorities.","status":"active","version":"1.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/Jimbly/http-proxy-node16","tags":["javascript","typescript"],"install":[{"cmd":"npm install http-proxy-node16","lang":"bash","label":"npm"},{"cmd":"yarn add http-proxy-node16","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-proxy-node16","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary factory function for creating a proxy instance. Supports both CommonJS (using destructuring `const { createProxyServer } = require(...)`) and ESM import styles.","wrong":"const createProxyServer = require('http-proxy-node16');","symbol":"createProxyServer","correct":"import { createProxyServer } from 'http-proxy-node16';"},{"note":"TypeScript interface for the proxy instance returned by `createProxyServer()`, providing methods like `web`, `ws`, `listen`, and `close`.","symbol":"ProxyServer","correct":"import type { ProxyServer } from 'http-proxy-node16';"},{"note":"TypeScript interface for the configuration object passed to `createProxyServer()`. Only use with `type` import for static type checking.","wrong":"import { ProxyServerOptions } from 'http-proxy-node16';","symbol":"ProxyServerOptions","correct":"import type { ProxyServerOptions } from 'http-proxy-node16';"},{"note":"CommonJS import of the entire module object, from which `httpProxy.createProxyServer` can then be accessed, mimicking older `node-http-proxy` patterns.","symbol":"Full module object (CommonJS)","correct":"const httpProxy = require('http-proxy-node16');"}],"quickstart":{"code":"const http = require('http');\nconst httpProxy = require('http-proxy');\n\n// Create your proxy server and set the target in the options.\n// It will listen on port 8000 and proxy requests to the target server on 9000.\nconst proxy = httpProxy.createProxyServer({ target: 'http://localhost:9000' });\nproxy.listen(8000);\n\n// Handle errors from the proxy server, essential for robust applications.\nproxy.on('error', function (err, req, res) {\n  console.error('Proxy error:', err);\n  res.writeHead(500, { 'Content-Type': 'text/plain' });\n  res.end('Something went wrong with the proxy.');\n});\n\n// Create your target server.\nhttp.createServer(function (req, res) {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.write('Request successfully proxied!' + '\\n' + JSON.stringify(req.headers, true, 2));\n  res.end();\n}).listen(9000);\n\nconsole.log('Proxy server listening on http://localhost:8000');\nconsole.log('Target server listening on http://localhost:9000');\nconsole.log('Try visiting http://localhost:8000 in your browser to see the proxy in action.');","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure your Node.js environment is at least v16.x for guaranteed compatibility and stability with this fork.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Instead of `proxy.listen(8000)`, consider `const server = http.createServer((req, res) => proxy.web(req, res, { target: '...' })); server.listen(8000);` for greater control.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The target server configured for the proxy (e.g., `http://localhost:9000`) is not running or not accessible.","error":"connect ECONNREFUSED 127.0.0.1:9000"},{"fix":"Provide a complete target URL string including protocol, host, and port (e.g., `{ target: 'http://localhost:3000' }`) in the proxy options.","cause":"The `target` option required by `createProxyServer` or `proxy.web`/`proxy.ws` methods was either missing or malformed.","error":"Error: Must provide a target protocol and host (e.g., http://localhost:8000)"},{"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.","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.","error":"Error: target server should listen on event 'upgrade' or be created by http.createServer.listen(port) with a 'ws' event."}],"ecosystem":"npm"}