Save time managing and deploying your node.js app. Code faster with jitsu and npm

Announcing http-proxy 1.0.0

About the author

nodejitsu nodejitsu

Here at Nodejitsu we have always been big fans of the Open Source movement. That is why we are super excited to announce that today we have released a new major version of node-http-proxy.

node-http-proxy is a library that makes it trivial for programmers to implement proxies, load balancers and cache servers using node.js and javascript. It is also one of the oldest and most mature modules maintained by the team. Its API has grown organically with Node.js itself: looking back it has run on every version of Node.js since 0.1.x! Many of the internals predated a stable Stream API in core, so with the advent of streams2 in node@0.10.x we knew the changes would be big.

Rewriting node-http-proxy was a big task, but over the last few months with the support of the Node.js community we were able create a leaner, meaner http-proxy@1.0.0! Why don't you read on to learn what's changed?

TL;DR? What changed?

If you're looking to use http-proxy with node 0.10.x, you've come in the right place! http-proxy@1.0 now works natively with the latest stable node version using streams2. We rewrote it from scratch to provide cleaner code and a more modular structure. As such, it is not backwards compatible with the previous versions.

No more buffering!

http-proxy@1.0 leverages the power of streams2 and seamlessly pauses/resumes the stream when needed.

New, leaner API

The new API was designed to be simple yet powerful. Two main functions are at the core of this new release: proxy.web and, which respectively proxy HTTP requests and Websocket requests. By narrowing down the API to just two main functions allowed us to greatly increase node-http-proxy's flexibility. It also meant that we needed to drop some old components whose functionalities should be now provided by the "userland" modules.

ProxyTable API

The ProxyTable APi is one of the components we removed to provide a leaner module structure, however have no fear! All that it was able to do and more is still achievable with the new APIs. Here's an example:

var httpProxy = require('http-proxy')

var proxy = httpProxy.createProxy();

var options = {  
  '': '',
  '': ''

require('http').createServer(function(req, res) {  
  proxy.web(req, res, {
    target: options[]


http-proxy@1.0 supports standalone mode like its predecessor

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

http.createServer(function(req, res) {  

var proxyServer = httpProxy.createProxyServer({  
  target: '', // where do we want to proxy to?
  ws    : true // proxy websockets as well 

createProxyServer() takes an options object as its only parameter that accepts the following properties:

  target : "<url string to be parsed with the url module>"
  forward: "<url string to be parsed with the url module>",
  agent : <object to be passed to http(s).request>
  ssl : <object to be passed to https.createServer()>
  ws : <true/false, if you want to proxy websockets>
  xfwd : <true/false, adds x-forward headers>
  secure : <true/false, verify SSL certificate>
  // NOTE: `` and `options.ssl` are optional.
  // ` and `options.forward` cannot be
  // both missing

HTTP Agents have been disabled by default in order to make it easier to include your own custom pooling logic. You can of course still rely on the builtin Agent that nodejs' http module provides.

Dynamic Proxying with custom logic

An object returned by .createProxyServer() exposes two methods: .web() and .ws() which proxy non-websockets and websockets requests.

They can be used as follows:

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

http.createServer(function(req, res) {  

var proxy = httpProxy.createProxy();

var proxyServer = http.createServer(function(req, res) {  
  if(req.path === 'forbidden') {
    return res.end('nope');

  proxy.web(req, res, {
    target: 'http://localhost:8000'


http-proxy@1.0 strives to be the best library out there for http proxying, but there's still a long way to go and we need your help to reach this goal!

Please test it out, submit issues and contribute with Pull Requests. We would love to hear some feedback from you.