GitHub - chimurai/http-proxy-middleware at v0.21.0 (original) (raw)

http-proxy-middleware

Build Status Coveralls dependency Status dependency Status code style: prettier

Node.js proxying made simple. Configure proxy middleware with ease for connect, express, browser-sync and many more.

Powered by the popular Nodejitsu http-proxy. GitHub stars

TL;DR

Proxy /api requests to http://www.example.org

var express = require('express'); var proxy = require('http-proxy-middleware');

var app = express();

app.use( '/api', proxy({ target: 'http://www.example.org', changeOrigin: true }) ); app.listen(3000);

// http://localhost:3000/api/foo/bar -> http://www.example.org/api/foo/bar

All http-proxy options can be used, along with some extra http-proxy-middleware options.

💡 Tip: Set the option changeOrigin to true for name-based virtual hosted sites.

Table of Contents

Install

$ npm install --save-dev http-proxy-middleware

Core concept

Proxy middleware configuration.

proxy([context,] config)

var proxy = require('http-proxy-middleware');

var apiProxy = proxy('/api', { target: 'http://www.example.org' }); // _/ __________________________/ // | | // context options

// 'apiProxy' is now ready to be used as middleware in a server.

(full list of http-proxy-middleware configuration options)

proxy(uri [, config])

// shorthand syntax for the example above: var apiProxy = proxy('http://www.example.org/api');

More about the shorthand configuration.

Example

An example with express server.

// include dependencies var express = require('express'); var proxy = require('http-proxy-middleware');

// proxy middleware options var options = { target: 'http://www.example.org', // target host changeOrigin: true, // needed for virtual hosted sites ws: true, // proxy websockets pathRewrite: { '^/api/old-path': '/api/new-path', // rewrite path '^/api/remove/path': '/path' // remove base path }, router: { // when request.headers.host == 'dev.localhost:3000', // override target 'http://www.example.org' to 'http://localhost:8000' 'dev.localhost:3000': 'http://localhost:8000' } };

// create the proxy (without context) var exampleProxy = proxy(options);

// mount exampleProxy in web server var app = express(); app.use('/api', exampleProxy); app.listen(3000);

Context matching

Providing an alternative way to decide which requests should be proxied; In case you are not able to use the server's path parameter to mount the proxy or when you need more flexibility.

RFC 3986 path is used for context matching.

         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment

Options

http-proxy-middleware options

http-proxy events

Subscribe to http-proxy events:

http-proxy options

The following options are provided by the underlying http-proxy library.

'use strict';  
const streamify = require('stream-array');  
const HttpProxy = require('http-proxy');  
const proxy = new HttpProxy();  
module.exports = (req, res, next) => {  
  proxy.web(req, res, {  
    target: 'http://localhost:4003/',  
    buffer: streamify(req.rawBody)  
  }, next);  
};

Shorthand

Use the shorthand syntax when verbose configuration is not needed. The context and option.target will be automatically configured when shorthand is used. Options can still be used if needed.

proxy('http://www.example.org:8000/api'); // proxy('/api', {target: 'http://www.example.org:8000'});

proxy('http://www.example.org:8000/api/books/*/**.json'); // proxy('/api/books/*/**.json', {target: 'http://www.example.org:8000'});

proxy('http://www.example.org:8000/api', { changeOrigin: true }); // proxy('/api', {target: 'http://www.example.org:8000', changeOrigin: true});

app.use(path, proxy)

If you want to use the server's app.use path parameter to match requests; Create and mount the proxy without the http-proxy-middleware context parameter:

app.use( '/api', proxy({ target: 'http://www.example.org', changeOrigin: true }) );

app.use documentation:

WebSocket

// verbose api proxy('/', { target: 'http://echo.websocket.org', ws: true });

// shorthand proxy('http://echo.websocket.org', { ws: true });

// shorter shorthand proxy('ws://echo.websocket.org');

External WebSocket upgrade

In the previous WebSocket examples, http-proxy-middleware relies on a initial http request in order to listen to the http upgrade event. If you need to proxy WebSockets without the initial http request, you can subscribe to the server's http upgrade event manually.

var wsProxy = proxy('ws://echo.websocket.org', { changeOrigin: true });

var app = express(); app.use(wsProxy);

var server = app.listen(3000); server.on('upgrade', wsProxy.upgrade); // <-- subscribe to http 'upgrade'

Working examples

View and play around with working examples.

Recipes

View the recipes for common use cases.

Compatible servers

http-proxy-middleware is compatible with the following servers:

Sample implementations can be found in the server recipes.

Tests

Run the test suite:

install dependencies

$ yarn

linting

$ yarn lint $ yarn lint:fix

building (compile typescript to js)

$ yarn build

unit tests

$ yarn test

code coverage

$ yarn cover

Changelog

License

The MIT License (MIT)

Copyright (c) 2015-2020 Steven Chim