node-http-proxy: a programmable HTTP and WebSocket proxy library for Node.js

What node-http-proxy actually is, and who writes code against it

The README describes node-http-proxy as an HTTP programmable proxying library that supports websockets, suitable for implementing components such as reverse proxies and load balancers. The word programmable is the whole point. This is not a binary you point at a config file. It is a module you require inside a Node.js process, and the proxy only exists because your code created it.

That shapes the audience. If you are writing an API gateway, a development server that forwards to a backend, a tenant router that picks a target per request, or a service that needs to terminate WebSocket upgrades and HTTP on the same port, this library gives you the primitives. If you want something that runs as a system service with a declarative config, this is the wrong shape of tool and no amount of reading the README will change that.

The package name on npm is http-proxy, while the repository is http-party/node-http-proxy. That mismatch trips people up when they search for the GitHub project and then try to install it. The README's installation line is explicit about which name goes to npm.

The two pipelines behind proxy.web() and proxy.ws()

Creating a proxy returns an object with four methods: web for HTTP(S) requests, ws for WS(S) requests, listen to wrap the object in a webserver, and close to shut it down. The README notes that calling createProxyServer on its own does not create a webserver; listen has to be invoked for that.

When a request is proxied it passes through two pipelines, both stored under lib/http-proxy/passes. The incoming pipeline builds and manipulates the stream connecting your client to the target. The outgoing pipeline handles the stream that returns data from the target to the client. Each pipeline is a sequence of passes, which is why the library exposes events at defined points rather than one monolithic handler.

That pass structure is what makes the event API useful. You can attach a listener for proxyReq and receive the http.ClientRequest, the incoming request, the server response and the options object, then set a header before the connection to the target is made. The README's header rewriting example does exactly that with setHeader. Errors arrive either through the EventEmitter API with proxy.on('error', ...) or through a callback passed as the fourth argument to proxy.web.

One design consequence worth naming: because you supply the server, you also supply the routing decision. The target can be a fixed string in options or a value computed per request. The library does not ship a routing table for you, though the README points at a ProxyTable API in its miscellaneous section and the repository carries an examples/balancer/ directory.

Installing http-proxy and proxying your first request

The README gives one install command. It saves the dependency to your package.json.

npm install http-proxy --save

The package.json in the repository declares engines of node >=8.0.0, so check that before you start. The runtime dependencies are eventemitter3, requires-port and follow-redirects, which is a small tree for a library that handles both HTTP and WebSocket traffic.

The smallest working setup is the README's stand-alone example. It creates a proxy with a fixed target and calls listen, which triggers creation of the webserver.

var http = require('http'),
    httpProxy = require('http-proxy');

httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000);

http.createServer(function (req, res) {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.write('request successfully proxied!');
  res.end();
}).listen(9000);

Run that file and request port 8000. The response body should read that the request was successfully proxied, which means traffic reached the target server on 9000 and came back through the proxy.

For most real work you want your own server so you can run logic before forwarding. That variant creates the proxy with an empty options object, then calls proxy.web inside your handler with the target supplied per request.

var proxy = httpProxy.createProxyServer({});

var server = http.createServer(function(req, res) {
  proxy.web(req, res, { target: 'http://127.0.0.1:5050' });
});

server.listen(5050);

Note the port collision in that pair of examples as printed: the proxy listens on 5050 and forwards to 5050. Change one of them before running it. The README's later header-rewriting example has the same shape, so read the ports rather than copying them.

Where node-http-proxy stops being the right tool

The library does not parse or rewrite response bodies for you. The README's section on modifying a response hands that job to Harmon, a separate project, and frames the choice as streaming so the pressure on the proxy stays low. If your requirement is HTML rewriting, injection or content transformation, you are assembling two projects, not using one.

Release cadence is the second constraint. The most recent release listed is 1.17.0, dated 2018-04-20, tagged in the changelog as long overdue maintenance. The repository's last push was on 2026-09-19, so commits continue, but the published version number has not moved in years. If your organisation requires a recent tagged release before adoption, that gap is a real blocker, and nothing in the README addresses it.

There is also a class of problem this library simply does not own: TLS certificate management, access control policy, rate limiting, and observability. It gives you the stream and the events. Everything above that layer is your code. Teams that expect a reverse proxy product with a config file and an admin surface will spend their first week writing what they assumed they were installing.

Finally, the README does not document rollback or a migration path beyond a link to UPGRADING.md for the 0.8.x transition. If you need documented downgrade behaviour, the README is silent.

How it differs from http-proxy-middleware and Express-http-proxy

The closest alternatives people reach for are http-proxy-middleware and Express-http-proxy. The difference is one of layer, not of quality.

http-proxy-middleware is a wrapper: it packages node-http-proxy into Connect-style middleware so an Express or Connect app can mount a proxy route with a path filter and options object. If your application is already an Express app and you want /api to forward to a backend, the middleware removes the need to write the server and the routing yourself. The trade-off is that you inherit the middleware's option surface and its abstraction over the underlying events. When you need to intervene at a specific pass, you are working through someone else's API.

Express-http-proxy takes a different route again, building proxying around Express request handling conventions rather than exposing the raw pipelines. It is a reasonable fit when everything you care about is an Express route, and a poor fit when you need WebSocket upgrades handled alongside HTTP on the same listener.

node-http-proxy sits underneath both. Choosing it directly buys you the proxyReq and error events, the two-pipeline model, and the ws method for WebSocket traffic, at the cost of writing the server, the routing and the error responses yourself. That is a fair trade for a gateway or a platform component, and a poor one for a single forwarding rule in an existing Express app.

Licence, upgrade cost and what the repository tells you about maintenance

The package.json declares the licence as MIT. The repository metadata reports the licence as NOASSERTION, which means the automated classifier could not confirm it from the repository contents alone. The practical reading is that the package manifest says MIT while the repository-level detection is unresolved, and anyone embedding this in a distributed product should confirm the LICENSE file themselves rather than relying on either signal. That is a diligence step, not legal advice.

Upgrade cost is unusually low in one direction and unusually opaque in another. Low, because the dependency list is three packages and the public surface is four methods plus events, so a version bump is unlikely to cascade. Opaque, because the last published release is 1.17.0 from 2018-04-20. A project that pins to a recent version has nothing newer to move to, and a project that tracks master is consuming unreleased commits. The CHANGELOG.md and the auto-changelog tooling in the repository suggest the maintainers intended release notes to be generated, but the version number in package.json is 1.18.1 while the release list stops at 1.17.0, so the published and in-repo versions do not line up.

The engines field of node >=8.0.0 is the other upgrade constraint to check. It is a floor, not a recommendation, and it tells you nothing about which modern Node.js versions have been exercised against the current code.

Testing and examples in the repository

The repository ships a test directory and a benchmark directory, plus an examples directory split into balancer, helpers, http, middleware and websocket. The npm test script runs mocha under nyc with text and lcov reporters, and the underlying mocha script targets test/*-test.js. That layout is useful for two reasons.

The examples directory is the fastest way to see the intended shape of a load balancer or a WebSocket setup without reading the whole README. The websocket and balancer folders correspond to the two capabilities the README leads with.

The test and benchmark folders tell you what the maintainers considered worth measuring and protecting. They do not tell you the results, and the README does not publish performance figures. Treat the presence of a benchmark directory as a sign that performance was considered, not as evidence of any particular throughput.

Editorial conclusion

Adopt node-http-proxy when you need proxy behaviour that lives inside a Node.js process you already control: header rewriting, per-request routing, WebSocket upgrades on the same port. Do not adopt it if you want a proxy you configure in a file and run as a daemon, or if you need a maintained release cadence; the last published release is 1.17.0 from 2018-04-20. Before committing, verify that your Node.js version satisfies the engines field of >=8.0.0 in package.json and check whether your framework already ships a proxy layer, since Express users may only need a middleware wrapper.

Frequently asked questions

Official sources

1. http-party/node-http-proxy on GitHub
2. Issues
3. Project website
4. README
5. Releases