node-http-proxy

http-proxy (published to npm as http-proxy, developed under the node-http-proxy repository name) is one of the oldest and most widely depended-on proxying libraries in the Node.js ecosystem. It exposes a createProxyServer factory that returns an object with web and ws methods, letting you proxy plain HTTP(S) requests and WebSocket upgrades from inside your own server or middleware stack rather than requiring a standalone process.

Requests flow through two ordered pipelines of small “pass” functions — one for incoming web traffic, one for WebSocket upgrades — that handle header rewriting, timeouts, X-Forwarded-* injection, cookie domain/path rewriting, and redirect location rewriting. The before/after API lets consumers splice custom passes into either pipeline, which is how the library has stayed relevant for over a decade as the proxying engine underneath tools like webpack-dev-server, Vite, and countless custom Express/Connect middleware setups.

What You Get

• Unified web + WebSocket proxying - a single ProxyServer instance exposes both .web() and .ws() methods so one proxy config handles regular HTTP(S) traffic and WebSocket upgrades.
• Pluggable pass pipeline - incoming and outgoing traffic each run through an ordered array of small pass functions, and before/after let you insert custom passes without forking the library.
• HTTPS and client-certificate support - ssl, secure, and pfx/passphrase options cover terminating HTTPS at the proxy and presenting client certificates to HTTPS targets.
• Cookie and redirect rewriting - cookieDomainRewrite, cookiePathRewrite, hostRewrite, autoRewrite, and protocolRewrite options rewrite Set-Cookie and Location headers so proxied responses stay valid for the client-facing host.
• Error-event model - proxy and target errors surface as error events on the ProxyServer (with a callback alternative per-call), matching Node’s own EventEmitter conventions instead of swallowing failures.
• follow-redirects integration - an optional followRedirects flag swaps in the follow-redirects package’s http(s) agents so the proxy itself follows upstream redirects transparently.

Common Use Cases

• Local dev-server proxying - forwarding /api requests from a webpack/Vite dev server to a separately-running backend during development.
• Reverse proxy in front of an app server - terminating TLS or adding headers in a thin Node process that forwards to an internal Express/Koa/Rails/etc. backend.
• WebSocket gateway - proxying upgrade events for real-time apps (chat, live dashboards) so WebSocket traffic and regular HTTP traffic share one edge process.
• Custom load balancing - wrapping createProxyServer in your own routing logic to pick a target per-request (e.g. round robin, sticky sessions) since the library itself is target-agnostic.
• Response interception/rewriting - using selfHandleResponse plus the proxyRes event to inspect or modify a proxied response body before returning it to the client (e.g. HTML rewriting via companion libraries like Harmon).

Under The Hood

Architecture The ProxyServer constructor (lib/http-proxy/index.js) wires two independent pipelines — webPasses and wsPasses — each built by mapping over the exported functions in lib/http-proxy/passes/web-incoming.js, web-outgoing.js, and ws-incoming.js. A shared createRightProxy(type) closure normalizes the optional trailing arguments (per-call options object, WebSocket head buffer, error callback) before iterating the applicable pass array; any pass that returns a truthy value halts the loop early, giving the pipeline an escape hatch similar to Express middleware next() but purely synchronous. lib/http-proxy/common.js centralizes the logic both pipelines depend on — building the outgoing request options, joining target and request paths, and rewriting cookie headers — so a change there ripples into both the HTTP and WebSocket code paths at once. The before/after methods splice extra passes directly into these arrays by name, which is the library’s main extensibility surface.

Tech Stack The runtime is plain, dependency-light CommonJS targeting Node >=8: only eventemitter3 (a faster drop-in EventEmitter used as ProxyServer’s base class), requires-port, and the optional follow-redirects agent swap-in are runtime dependencies. There is no build/transpile step — the shipped code is the source. Test tooling runs on mocha with nyc for coverage and expect.js for assertions, exercising real HTTP/WS servers via ws, socket.io, socket.io-client, and sse rather than mocking the network layer, with Travis CI historically running the suite across Node 8/10/12 and reporting to Codecov.

Code Quality The test suite is comprehensive in scope — covering the createProxyServer factory, forwarding, HTTPS, WebSocket upgrades, and each individual pass — though it uses the older expect.js assertion style and a couple of tests are explicitly skipped rather than fixed. Error handling follows Node’s own convention of surfacing failures as error events (with a deliberate re-throw if no listener is attached, mirroring core EventEmitter behavior) rather than silently discarding them. There is no bundled linter or formatter configuration, and the codebase predates widespread TypeScript adoption, so type safety comes only from an external @types package rather than from the repo itself.

What Makes It Unique Rather than being a full-featured reverse proxy or API gateway with its own configuration DSL, http-proxy stays deliberately minimal: a small, composable pass-pipeline abstraction plus a handful of rewrite hooks, meant to be embedded inside another server rather than run standalone. That minimalism, combined with over a decade of production use, is why it ended up as the proxying engine underneath many higher-level dev tools (webpack-dev-server and similar) instead of those tools reimplementing proxying themselves.