Node Proxy Middleware
http-proxy-middleware – npm
-proxy-middleware2. 0. 1 • Public • Published 3 months ago Readme Explore BETA5 Dependencies2, 558 Dependents72 Versions
proxying made simple. Configure proxy middleware with ease for connect, express, browser-sync and many more.
Powered by the popular Nodejitsu -proxy.
⚠️ Note
This page is showing documentation for version v1. x. x (release notes)
If you’re looking for v0. x documentation. Go to:
TL;DR
Proxy /api requests to // javascript
const express = require(‘express’);
const { createProxyMiddleware} = require(‘-proxy-middleware’);
const app = express();
(‘/api’, createProxyMiddleware({ target: ”, changeOrigin: true}));
(3000);
// localhost:3000/api/foo/bar -> // typescript
import * as express from ‘express’;
import { createProxyMiddleware, Filter, Options, RequestHandler} from ‘-proxy-middleware’;
// localhost:3000/api/foo/bar -> All -proxy options can be used, along with some extra -proxy-middleware options.
Tip: Set the option changeOrigin to true for name-based virtual hosted sites.
Table of Contents
Install
Core concept
Example
Context matching
Options
-proxy-middleware options
-proxy events
-proxy options
Shorthand
(path, proxy)
WebSocket
External WebSocket upgrade
Intercept and manipulate requests
Intercept and manipulate responses
Working examples
Recipes
Compatible servers
Tests
Changelog
License
$ npm install –save-dev -proxy-middleware
Proxy middleware configuration.
createProxyMiddleware([context, ] config)
const apiProxy = createProxyMiddleware(‘/api’, { target: ”});
// \____/ \_____________________________/
// | |
// context options
// ‘apiProxy’ is now ready to be used as middleware in a server.
context: Determine which requests should be proxied to the target host.
(more on context matching)
target host to proxy to. (protocol + host)
(full list of -proxy-middleware configuration options)
createProxyMiddleware(uri [, config])
// shorthand syntax for the example above:
const apiProxy = createProxyMiddleware(”);
More about the shorthand configuration.
An example with express server.
// include dependencies
// proxy middleware options
const options = {
target: ”, // 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 == ‘dev. localhost:3000’,
// override target ” to ‘localhost:8000’
‘dev. localhost:3000’: ‘localhost:8000’, }, };
// create the proxy (without context)
const exampleProxy = createProxyMiddleware(options);
// mount `exampleProxy` in web server
(‘/api’, exampleProxy);
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
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
path matching
createProxyMiddleware({… }) – matches any path, all requests will be proxied.
createProxyMiddleware(‘/’, {… }) – matches any path, all requests will be proxied.
createProxyMiddleware(‘/api’, {… }) – matches paths starting with /api
multiple path matching
createProxyMiddleware([‘/api’, ‘/ajax’, ‘/someotherpath’], {… })
wildcard path matching
For fine-grained control you can use wildcard matching. Glob pattern matching is done by micromatch. Visit micromatch or glob for more globbing examples.
createProxyMiddleware(‘**’, {… }) matches any path, all requests will be proxied.
createProxyMiddleware(‘**/*’, {… }) matches any path which ends with
createProxyMiddleware(‘/*’, {… }) matches paths directly under path-absolute
createProxyMiddleware(‘/api/**/*’, {… }) matches requests ending with in the path of /api
createProxyMiddleware([‘/api/**’, ‘/ajax/**’], {… }) combine multiple patterns
createProxyMiddleware([‘/api/**’, ‘! **/’], {… }) exclusion
Note: In multiple path matching, you cannot use string paths and wildcard paths together.
custom matching
For full control you can provide a custom function to determine which requests should be proxied or not.
/**
* @return {Boolean}
*/
const filter = function (pathname, req) {
return (‘^/api’) && === ‘GET’;};
const apiProxy = createProxyMiddleware(filter, {
target: ”, });
thRewrite: object/function, rewrite target’s url path. Object-keys will be used as RegExp to match paths.
// rewrite path
pathRewrite: {‘^/old/api’: ‘/new/api’}
// remove path
pathRewrite: {‘^/remove/api’: ”}
// add base path
pathRewrite: {‘^/’: ‘/basepath/’}
// custom rewriting
pathRewrite: function (path, req) { return place(‘/api’, ‘/base/api’)}
// custom rewriting, returning Promise
pathRewrite: async function (path, req) {
const should_add_something = await RequestToDecideSomething(path);
if (should_add_something) path += “something”;
return path;}
object/function, re-target for specific requests.
// Use `host` and/or `path` to match requests. First match will be used.
// The order of the configuration matters.
‘integration. localhost:3000’: ‘localhost:8001’, // host only
‘staging. localhost:3000’: ‘localhost:8002’, // host only
‘localhost:3000/api’: ‘localhost:8003’, // host + path
‘/rest’: ‘localhost:8004’ // path only}
// Custom router function (string target)
router: function(req) {
return ‘localhost:8004’;}
// Custom router function (target object)
return {
protocol: ‘:’, // The: is required
host: ‘localhost’,
port: 8004};}
// Asynchronous router function which returns promise
router: async function(req) {
const url = await doSomeIO();
return url;}
option. logLevel: string, [‘debug’, ‘info’, ‘warn’, ‘error’, ‘silent’]. Default: ‘info’
option. logProvider: function, modify or replace log provider. Default: console.
// simple replace
function logProvider(provider) {
// replace the default console log provider.
return require(‘winston’);}
// verbose replacement
const logger = new (require(‘winston’))();
const myCustomProvider = {
log:,
debug:,
info:,
warn:,
error:, };
return myCustomProvider;}
Subscribe to -proxy events:
rror: function, subscribe to -proxy’s error event for custom error handling.
function onError(err, req, res, target) {
res. writeHead(500, {
‘Content-Type’: ‘text/plain’, });
(‘Something went wrong. And we are reporting a custom error message. ‘);}
option. onProxyRes: function, subscribe to -proxy’s proxyRes event.
function onProxyRes(proxyRes, req, res) {
proxyRes. headers[‘x-added’] = ‘foobar’; // add new header to response
delete proxyRes. headers[‘x-removed’]; // remove header from response}
option. onProxyReq: function, subscribe to -proxy’s proxyReq event.
function onProxyReq(proxyReq, req, res) {
// add custom header to request
tHeader(‘x-added’, ‘foobar’);
// or log the req}
option. onProxyReqWs: function, subscribe to -proxy’s proxyReqWs event.
function onProxyReqWs(proxyReq, req, socket, options, head) {
// add custom header
tHeader(‘X-Special-Proxy-Header’, ‘foobar’);}
function, subscribe to -proxy’s open event.
function onOpen(proxySocket) {
// listen for messages coming FROM the target here
(‘data’, hybiParseAndLogMessage);}
option. onClose: function, subscribe to -proxy’s close event.
function onClose(res, socket, head) {
// view disconnected websocket connections
(‘Client disconnected’);}
The following options are provided by the underlying -proxy library.
url string to be parsed with the url module
rward: url string to be parsed with the url module
object to be passed to (s). request (see Node’s agent and agent objects)
object to be passed to eateServer()
true/false: if you want to proxy websockets
true/false, adds x-forward headers
true/false, if you want to verify the SSL Certs
Proxy: true/false, passes the absolute URL as the path (useful for proxying to proxies)
ependPath: true/false, Default: true – specify whether you want to prepend the target’s path to the proxy path
option. ignorePath: true/false, Default: false – specify whether you want to ignore the proxy path of the incoming request (note: you will have to append / manually if required).
option. localAddress: Local interface string to bind for outgoing connections
angeOrigin: true/false, Default: false – changes the origin of the host header to the target URL
eserveHeaderKeyCase: true/false, Default: false – specify whether you want to keep letter case of response header key: Basic authentication i. e. ‘user:password’ to compute an Authorization header.
Rewrite: rewrites the location hostname on (301/302/307/308) redirects.
toRewrite: rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
otocolRewrite: rewrites the location protocol on (301/302/307/308) redirects to ” or ”. Default: null.
okieDomainRewrite: rewrites domain of set-cookie headers. Possible values:
false (default): disable cookie rewriting
String: new domain, for example cookieDomainRewrite: “”. To remove the domain, use cookieDomainRewrite: “”.
Object: mapping of domains to new domains, use “*” to match all domains.
For example keep one domain unchanged, rewrite one domain and remove other domains:
cookieDomainRewrite: {
“”: “”,
“*”: “”}
okiePathRewrite: rewrites path of set-cookie headers. Possible values:
String: new path, for example cookiePathRewrite: “/newPath/”. To remove the path, use cookiePathRewrite: “”. To set path to root use cookiePathRewrite: “/”.
Object: mapping of paths to new paths, use “*” to match all paths.
For example, to keep one path unchanged, rewrite one path and remove other paths:
cookiePathRewrite: {
“/”: “/”,
option. headers: object, adds request headers. (Example: {host:”})
oxyTimeout: timeout (in millis) when proxy receives no response from target
option. timeout: timeout (in millis) for incoming requests
llowRedirects: true/false, Default: false – specify whether you want to follow redirects
lfHandleResponse true/false, if set to true, none of the webOutgoing passes are called and it’s your responsibility to appropriately return the response by listening and acting on the proxyRes event
stream of data to send as the request body. Maybe you have some middleware that consumes the request stream before proxying it on e. g. If you read the body of a request into a field called ‘req. rawbody’ you could restream this field in the buffer option:
‘use strict’;
const streamify = require(‘stream-array’);
const HttpProxy = require(‘-proxy’);
const proxy = new HttpProxy();
module. exports = (req, res, next) => {
(
req,
res,
{
target: ‘localhost:4003/’,
buffer: streamify(req. rawBody), },
next);};
Use the shorthand syntax when verbose configuration is not needed. The context and will be automatically configured when shorthand is used. Options can still be used if needed.
createProxyMiddleware(”);
// createProxyMiddleware(‘/api’, {target: ”});
createProxyMiddleware(‘/**’);
// createProxyMiddleware(‘/api/books/*/**’, {target: ”});
createProxyMiddleware(”, { changeOrigin: true});
// createProxyMiddleware(‘/api’, {target: ”, changeOrigin: true});
If you want to use the server’s path parameter to match requests;
Create and mount the proxy without the -proxy-middleware context parameter:
documentation:
express:
connect:
polka:
// verbose api
createProxyMiddleware(‘/’, { target: ”, ws: true});
// shorthand
createProxyMiddleware(”, { ws: true});
// shorter shorthand
createProxyMiddleware(‘ws’);
In the previous WebSocket examples, -proxy-middleware relies on a initial request in order to listen to the upgrade event. If you need to proxy WebSockets without the initial request, you can subscribe to the server’s upgrade event manually.
const wsProxy = createProxyMiddleware(‘ws’, { changeOrigin: true});
(wsProxy);
const server = (3000);
(‘upgrade’, wsProxy. upgrade); // <-- subscribe to 'upgrade'
Intercept requests from downstream by defining onProxyReq in createProxyMiddleware.
Currently the only pre-provided request interceptor is fixRequestBody, which is used to fix proxied POST requests when bodyParser is applied before this middleware.
Example:
const { createProxyMiddleware, fixRequestBody} = require('-proxy-middleware');
const proxy = createProxyMiddleware({
* Fix bodyParser
**/
onProxyReq: fixRequestBody, });
Intercept responses from upstream with responseInterceptor. (Make sure to set selfHandleResponse: true)
Responses which are compressed with brotli, gzip and deflate will be decompressed automatically. The response will be returned as buffer (docs) which you can manipulate.
With buffer, response manipulation is not limited to text responses (html/css/js, etc... ); image manipulation will be possible too. (example)
NOTE: responseInterceptor disables streaming of target's response.
const { createProxyMiddleware, responseInterceptor} = require('-proxy-middleware');
* IMPORTANT: avoid being called automatically
selfHandleResponse: true, // () will be called internally by responseInterceptor()
* Intercept response and replace 'Hello' with 'Goodbye'
onProxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
const response = String(‘utf8’); // convert buffer to string
return place(‘Hello’, ‘Goodbye’); // manipulate response and return the result}), });
Check out interception recipes for more examples.
View and play around with working examples.
Browser-Sync (example source)
express (example source)
connect (example source)
WebSocket (example source)
Response Manipulation (example source)
View the recipes for common use cases.
-proxy-middleware is compatible with the following servers:
connect
express
fastify
browser-sync
lite-server
polka
grunt-contrib-connect
grunt-browser-sync
gulp-connect
gulp-webserver
Sample implementations can be found in the server recipes.
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
View changelog
The MIT License (MIT)
Copyright (c) 2015-2021 Steven Chim
Keywordsreverseproxymiddlewareconnectexpressfastifypolkabrowser-syncgulpgrunt-contrib-connectwebsocketwscors
chimurai/http-proxy-middleware – GitHub
proxying made simple. Configure proxy middleware with ease for connect, express, browser-sync and many more.
Powered by the popular Nodejitsu -proxy.
⚠️ Note
This page is showing documentation for version v1. x. x (release notes)
If you’re looking for v0. x documentation. Go to:
TL;DR
Proxy /api requests to // javascript
const express = require(‘express’);
const { createProxyMiddleware} = require(‘-proxy-middleware’);
const app = express();
(‘/api’, createProxyMiddleware({ target: ”, changeOrigin: true}));
(3000);
// localhost:3000/api/foo/bar -> // typescript
import * as express from ‘express’;
import { createProxyMiddleware, Filter, Options, RequestHandler} from ‘-proxy-middleware’;
// localhost:3000/api/foo/bar -> All -proxy options can be used, along with some extra -proxy-middleware options.
Tip: Set the option changeOrigin to true for name-based virtual hosted sites.
Table of Contents
Install
Core concept
Example
Context matching
Options
-proxy-middleware options
-proxy events
-proxy options
Shorthand
(path, proxy)
WebSocket
External WebSocket upgrade
Intercept and manipulate requests
Intercept and manipulate responses
Working examples
Recipes
Compatible servers
Tests
Changelog
License
$ npm install –save-dev -proxy-middleware
Proxy middleware configuration.
createProxyMiddleware([context, ] config)
const apiProxy = createProxyMiddleware(‘/api’, { target: ”});
// \____/ \_____________________________/
// | |
// context options
// ‘apiProxy’ is now ready to be used as middleware in a server.
context: Determine which requests should be proxied to the target host.
(more on context matching)
target host to proxy to. (protocol + host)
(full list of -proxy-middleware configuration options)
createProxyMiddleware(uri [, config])
// shorthand syntax for the example above:
const apiProxy = createProxyMiddleware(”);
More about the shorthand configuration.
An example with express server.
// include dependencies
// proxy middleware options
const options = {
target: ”, // 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 == ‘dev. localhost:3000’,
// override target ” to ‘localhost:8000’
‘dev. localhost:3000’: ‘localhost:8000’, }, };
// create the proxy (without context)
const exampleProxy = createProxyMiddleware(options);
// mount `exampleProxy` in web server
(‘/api’, exampleProxy);
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
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
path matching
createProxyMiddleware({… }) – matches any path, all requests will be proxied.
createProxyMiddleware(‘/’, {… }) – matches any path, all requests will be proxied.
createProxyMiddleware(‘/api’, {… }) – matches paths starting with /api
multiple path matching
createProxyMiddleware([‘/api’, ‘/ajax’, ‘/someotherpath’], {… })
wildcard path matching
For fine-grained control you can use wildcard matching. Glob pattern matching is done by micromatch. Visit micromatch or glob for more globbing examples.
createProxyMiddleware(‘**’, {… }) matches any path, all requests will be proxied.
createProxyMiddleware(‘**/*’, {… }) matches any path which ends with
createProxyMiddleware(‘/*’, {… }) matches paths directly under path-absolute
createProxyMiddleware(‘/api/**/*’, {… }) matches requests ending with in the path of /api
createProxyMiddleware([‘/api/**’, ‘/ajax/**’], {… }) combine multiple patterns
createProxyMiddleware([‘/api/**’, ‘! **/’], {… }) exclusion
Note: In multiple path matching, you cannot use string paths and wildcard paths together.
custom matching
For full control you can provide a custom function to determine which requests should be proxied or not.
/**
* @return {Boolean}
*/
const filter = function (pathname, req) {
return (‘^/api’) && === ‘GET’;};
const apiProxy = createProxyMiddleware(filter, {
target: ”, });
thRewrite: object/function, rewrite target’s url path. Object-keys will be used as RegExp to match paths.
// rewrite path
pathRewrite: {‘^/old/api’: ‘/new/api’}
// remove path
pathRewrite: {‘^/remove/api’: ”}
// add base path
pathRewrite: {‘^/’: ‘/basepath/’}
// custom rewriting
pathRewrite: function (path, req) { return place(‘/api’, ‘/base/api’)}
// custom rewriting, returning Promise
pathRewrite: async function (path, req) {
const should_add_something = await RequestToDecideSomething(path);
if (should_add_something) path += “something”;
return path;}
object/function, re-target for specific requests.
// Use `host` and/or `path` to match requests. First match will be used.
// The order of the configuration matters.
‘integration. localhost:3000’: ‘localhost:8001’, // host only
‘staging. localhost:3000’: ‘localhost:8002’, // host only
‘localhost:3000/api’: ‘localhost:8003’, // host + path
‘/rest’: ‘localhost:8004’ // path only}
// Custom router function (string target)
router: function(req) {
return ‘localhost:8004’;}
// Custom router function (target object)
return {
protocol: ‘:’, // The: is required
host: ‘localhost’,
port: 8004};}
// Asynchronous router function which returns promise
router: async function(req) {
const url = await doSomeIO();
return url;}
option. logLevel: string, [‘debug’, ‘info’, ‘warn’, ‘error’, ‘silent’]. Default: ‘info’
option. logProvider: function, modify or replace log provider. Default: console.
// simple replace
function logProvider(provider) {
// replace the default console log provider.
return require(‘winston’);}
// verbose replacement
const logger = new (require(‘winston’))();
const myCustomProvider = {
log:,
debug:,
info:,
warn:,
error:, };
return myCustomProvider;}
Subscribe to -proxy events:
rror: function, subscribe to -proxy’s error event for custom error handling.
function onError(err, req, res, target) {
res. writeHead(500, {
‘Content-Type’: ‘text/plain’, });
(‘Something went wrong. And we are reporting a custom error message. ‘);}
option. onProxyRes: function, subscribe to -proxy’s proxyRes event.
function onProxyRes(proxyRes, req, res) {
proxyRes. headers[‘x-added’] = ‘foobar’; // add new header to response
delete proxyRes. headers[‘x-removed’]; // remove header from response}
option. onProxyReq: function, subscribe to -proxy’s proxyReq event.
function onProxyReq(proxyReq, req, res) {
// add custom header to request
tHeader(‘x-added’, ‘foobar’);
// or log the req}
option. onProxyReqWs: function, subscribe to -proxy’s proxyReqWs event.
function onProxyReqWs(proxyReq, req, socket, options, head) {
// add custom header
tHeader(‘X-Special-Proxy-Header’, ‘foobar’);}
function, subscribe to -proxy’s open event.
function onOpen(proxySocket) {
// listen for messages coming FROM the target here
(‘data’, hybiParseAndLogMessage);}
option. onClose: function, subscribe to -proxy’s close event.
function onClose(res, socket, head) {
// view disconnected websocket connections
(‘Client disconnected’);}
The following options are provided by the underlying -proxy library.
url string to be parsed with the url module
rward: url string to be parsed with the url module
object to be passed to (s). request (see Node’s agent and agent objects)
object to be passed to eateServer()
true/false: if you want to proxy websockets
true/false, adds x-forward headers
true/false, if you want to verify the SSL Certs
Proxy: true/false, passes the absolute URL as the path (useful for proxying to proxies)
ependPath: true/false, Default: true – specify whether you want to prepend the target’s path to the proxy path
option. ignorePath: true/false, Default: false – specify whether you want to ignore the proxy path of the incoming request (note: you will have to append / manually if required).
option. localAddress: Local interface string to bind for outgoing connections
angeOrigin: true/false, Default: false – changes the origin of the host header to the target URL
eserveHeaderKeyCase: true/false, Default: false – specify whether you want to keep letter case of response header key: Basic authentication i. e. ‘user:password’ to compute an Authorization header.
Rewrite: rewrites the location hostname on (301/302/307/308) redirects.
toRewrite: rewrites the location host/port on (301/302/307/308) redirects based on requested host/port. Default: false.
otocolRewrite: rewrites the location protocol on (301/302/307/308) redirects to ” or ”. Default: null.
okieDomainRewrite: rewrites domain of set-cookie headers. Possible values:
false (default): disable cookie rewriting
String: new domain, for example cookieDomainRewrite: “”. To remove the domain, use cookieDomainRewrite: “”.
Object: mapping of domains to new domains, use “*” to match all domains.
For example keep one domain unchanged, rewrite one domain and remove other domains:
cookieDomainRewrite: {
“”: “”,
“*”: “”}
okiePathRewrite: rewrites path of set-cookie headers. Possible values:
String: new path, for example cookiePathRewrite: “/newPath/”. To remove the path, use cookiePathRewrite: “”. To set path to root use cookiePathRewrite: “/”.
Object: mapping of paths to new paths, use “*” to match all paths.
For example, to keep one path unchanged, rewrite one path and remove other paths:
cookiePathRewrite: {
“/”: “/”,
option. headers: object, adds request headers. (Example: {host:”})
oxyTimeout: timeout (in millis) when proxy receives no response from target
option. timeout: timeout (in millis) for incoming requests
llowRedirects: true/false, Default: false – specify whether you want to follow redirects
lfHandleResponse true/false, if set to true, none of the webOutgoing passes are called and it’s your responsibility to appropriately return the response by listening and acting on the proxyRes event
stream of data to send as the request body. Maybe you have some middleware that consumes the request stream before proxying it on e. g. If you read the body of a request into a field called ‘req. rawbody’ you could restream this field in the buffer option:
‘use strict’;
const streamify = require(‘stream-array’);
const HttpProxy = require(‘-proxy’);
const proxy = new HttpProxy();
module. exports = (req, res, next) => {
(
req,
res,
{
target: ‘localhost:4003/’,
buffer: streamify(req. rawBody), },
next);};
Use the shorthand syntax when verbose configuration is not needed. The context and will be automatically configured when shorthand is used. Options can still be used if needed.
createProxyMiddleware(”);
// createProxyMiddleware(‘/api’, {target: ”});
createProxyMiddleware(‘/**’);
// createProxyMiddleware(‘/api/books/*/**’, {target: ”});
createProxyMiddleware(”, { changeOrigin: true});
// createProxyMiddleware(‘/api’, {target: ”, changeOrigin: true});
If you want to use the server’s path parameter to match requests;
Create and mount the proxy without the -proxy-middleware context parameter:
documentation:
express: connect: polka:
// verbose api
createProxyMiddleware(‘/’, { target: ”, ws: true});
// shorthand
createProxyMiddleware(”, { ws: true});
// shorter shorthand
createProxyMiddleware(‘ws’);
In the previous WebSocket examples, -proxy-middleware relies on a initial request in order to listen to the upgrade event. If you need to proxy WebSockets without the initial request, you can subscribe to the server’s upgrade event manually.
const wsProxy = createProxyMiddleware(‘ws’, { changeOrigin: true});
(wsProxy);
const server = (3000);
(‘upgrade’, wsProxy. upgrade); // <-- subscribe to 'upgrade'
Intercept requests from downstream by defining onProxyReq in createProxyMiddleware.
Currently the only pre-provided request interceptor is fixRequestBody, which is used to fix proxied POST requests when bodyParser is applied before this middleware.
Example:
const { createProxyMiddleware, fixRequestBody} = require('-proxy-middleware');
const proxy = createProxyMiddleware({
* Fix bodyParser
**/
onProxyReq: fixRequestBody, });
Intercept responses from upstream with responseInterceptor. (Make sure to set selfHandleResponse: true)
Responses which are compressed with brotli, gzip and deflate will be decompressed automatically. The response will be returned as buffer (docs) which you can manipulate.
With buffer, response manipulation is not limited to text responses (html/css/js, etc... ); image manipulation will be possible too. (example)
NOTE: responseInterceptor disables streaming of target's response.
const { createProxyMiddleware, responseInterceptor} = require('-proxy-middleware');
* IMPORTANT: avoid being called automatically
selfHandleResponse: true, // () will be called internally by responseInterceptor()
* Intercept response and replace 'Hello' with 'Goodbye'
onProxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
const response = String(‘utf8’); // convert buffer to string
return place(‘Hello’, ‘Goodbye’); // manipulate response and return the result}), });
Check out interception recipes for more examples.
View and play around with working examples.
Browser-Sync (example source)
express (example source)
connect (example source)
WebSocket (example source)
Response Manipulation (example source)
View the recipes for common use cases.
-proxy-middleware is compatible with the following servers:
connect
express
fastify
browser-sync
lite-server
polka
grunt-contrib-connect
grunt-browser-sync
gulp-connect
gulp-webserver
Sample implementations can be found in the server recipes.
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
View changelog
The MIT License (MIT)
Copyright (c) 2015-2021 Steven Chim
Build a Node.js Proxy Server in Under 10 minutes! – Twilio
We have all heard the term “proxy”. It might sound like it’s some kind of portal to a new dimension from the Matrix movies, but it turns out it’s very very useful!
In a nutshell, a proxy is an intermediary application which sits between two (or more) services and processes/modifies the requests and responses in both directions. This sounds complicated, I know, but let’s try with a simpler analogy:
Imagine you meet someone from Spain, but you don’t speak Spanish. What do you do? Well, you remember that your friend Santiago knows both Spanish and English and can translate for you.
The process goes like this:
You tell something to Santiago in English
Santiago translates it to Spanish in his head and says it in Spanish to your new friend
Your new friend replies back to Santiago in Spanish
Santiago then translates it in his head and tells you the response in English
Santiago in this case serves as a proxy between you and your new friend. You can’t speak directly to each other but thanks to the translator you can relay messages (i. e. requests and responses) and have a conversation!
Okay, now that we know what a proxy is, what are the use cases for it? Well, here are a few that we, at Twilio, find really useful:
Authorization – Forward only requests that are authorized to access a service
Load balancing – Distribute the requests equally among many instances
Logging – Log every requests going to a Back End API service
And many more…
Now that you know what a proxy is and why it is useful, let’s build a simple one using!
Prerequisites
To follow along, you need and Yarn installed, which are available on Mac, Windows and Linux distributions.
Build the simple proxy
In a few easy steps we are going to create a simple proxy in which can forward requests to multiple different servers/endpoints!
The full code which will be implemented step-by-step is available on GitHub here.
Initialize the project
Let’s start by initiating a new node project:
This will generate a file which will contain a basic project configuration. The command will prompt you with multiple questions (name, version, description, etc. ) – you can click ‘Enter’ on all of them to accept the default values (for example, by default the entry point will be).
Install dependencies
We need a few packages to make the proxy work:
express: Minimalist web framework
-proxy-middleware: Simple proxy framework
(optional) morgan – HTTP request logger middleware
which we can install by running:
yarn add express -proxy-middleware morgan
Define a start command
We need to add a start command to our project, so after a small change, your file should look like this (Depending on when you install these packages, some version numbers might differ, but their core functionality should stay the same. If the behaviour is drastically different, check their latest documentations. ):
{
“name”: “simple-nodejs-proxy”,
“version”: “1. 0. 0”,
“main”: “”,
“license”: “MIT”,
“dependencies”: {
“express”: “^4. 17. 1”,
“-proxy-middleware”: “^1. 5”,
“morgan”: “^1. 10. 0”},
“scripts”: {
“start”: “node “}}
If we now add an empty file, we can execute the project through:
This should run the file. Because the file is empty the console output should also be empty.
But enough configurations, let’s actually proxy some requests!
Create a simple proxy
This is where the interesting bits begin. Go ahead and open the file and add the necessary imports:
const express = require(‘express’);
const morgan = require(“morgan”);
const { createProxyMiddleware} = require(‘-proxy-middleware’);
Now we can create a basic express server and define some constants which we will use later:
// Create Express Server
const app = express();
// Configuration
const PORT = 3000;
const HOST = “localhost”;
const API_SERVICE_URL = “;
Before we implement the proxy logic, we can add the morgan middleware which logs the incoming requests:
// Logging
(morgan(‘dev’));
To be able to test that we proxy only what we want, let’s add a mock /info endpoint which doesn’t forward the request, but rather returns a simple text response:
// Info GET endpoint
(‘/info’, (req, res, next) => {
(‘This is a proxy service which proxies to Billing and Account APIs. ‘);});
Before defining the proxy endpoints, let’s also add a simple authorization/permission handling middleware which sends 403 (Forbidden) if the Authorization Header is missing:
// Authorization
(”, (req, res, next) => {
if (thorization) {
next();} else {
ndStatus(403);}});
Then we define the proxy endpoint. We want to proxy all requests starting with /json_placeholder to the notorious JSONPlaceholder API (a simple mock API which contains multiple endpoints supporting all HTTP methods). We also define a pathRewrite so that /json_placeholder is omitted when forwarded to the API:
// Proxy endpoints
(‘/json_placeholder’, createProxyMiddleware({
target: API_SERVICE_URL,
changeOrigin: true,
pathRewrite: {
[`^/json_placeholder`]: ”, }, }));
This way, when we, for example, send a request to localhost:3000/json_placeholder/posts/1, the URL will be rewritten to
And, last but not least, we start the configured server with this function call:
// Start the Proxy
(PORT, HOST, () => {
(`Starting Proxy at ${HOST}:${PORT}`);});
Run the proxy
Let’s start the proxy with the following command:
This prints something along the lines of:
yarn run v1. 22. 4
$ node
[HPM] Proxy created: / -> [HPM] Proxy rewrite rule created: “^/json_placeholder” ~> “”
Starting Proxy at localhost:3000
The proxy should now be running and if we open a second terminal and send a GET request to the /info:
We should receive a response from our proxy. And, unsurprisingly, we get:
This is a proxy service which proxies to JSONPlaceholder API.
Okay, this is great and all, but we don’t want some boring GET endpoints, we want to proxy!
In order to test the proxying, we can send a new GET request like this:
curl localhost:3000/json_placeholder/posts/1
Oh, no! This returns:
Fear not, this is expected because we included the authorization middleware which requires that every request contains an Authorization Header. So, make this small modification (you can even change it to your name because due to the simplicity of our authorization step, every name would work! ):
curl -H “Authorization: nikolay” localhost:3000/json_placeholder/posts/1
This gives us:
“userId”: 1,
“id”: 1,
“title”: “sunt aut facere repellat provident occaecati excepturi optio reprehenderit”,
“body”: “quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto”}
Hooray! Your first successfully proxied request! We can even try this with a POST request:
curl -X POST -H “Authorization: real_user” –data ‘{“title”: “Build a Proxy Server in Under 10 minutes! “, “body”: “We have all heard the term “proxy”… “, userId=”1”}’ localhost:3000/json_placeholder/posts
The POST request works as expected:
“{\”title\””: \””Build a Proxy Server in Under 10 minutes! \””
