/ stream.nieuweinstituut.nl / node_modules / http-proxy-middleware /

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[DIR]dist/2 years ago -  
[DIR]node_modules/2 years ago -  
[TXT]CHANGELOG.md39 years ago 11K 
[   ]LICENSE39 years ago1.1K 
[   ]package.json2 years ago3.6K3e510ca test new git [كارل مبارك]
[TXT]README.md39 years ago 22Kd768d73 docs [كارل مبارك]
README.md

http-proxy-middleware

GitHub Workflow Status (branch) Coveralls dependency Status dependency Status npm

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

⚠️ Note

This page is showing documentation for version v1.x.x (release notes)

If you're looking for v0.x documentation. Go to: https://github.com/chimurai/http-proxy-middleware/tree/v0.21.0#readme

TL;DR

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

// javascript

const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

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

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

import * as express from 'express';
import { createProxyMiddleware, Filter, Options, RequestHandler } from 'http-proxy-middleware';

const app = express();

app.use('/api', createProxyMiddleware({ 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.

:bulb: 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.

createProxyMiddleware([context,] config)

const { createProxyMiddleware } = require('http-proxy-middleware');

const apiProxy = createProxyMiddleware('/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)

createProxyMiddleware(uri [, config])

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

More about the shorthand configuration.

Example

An example with express server.

// include dependencies
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

// proxy middleware options
const 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)
const exampleProxy = createProxyMiddleware(options);

// mount `exampleProxy` in web server
const 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.

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.

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

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

createProxyMiddleware('http://www.example.org:8000/api', { changeOrigin: true });
// createProxyMiddleware('/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', createProxyMiddleware({ target: 'http://www.example.org', changeOrigin: true }));

app.use documentation:

WebSocket

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

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

// shorter shorthand
createProxyMiddleware('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.

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

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

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

Intercept and manipulate requests

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('http-proxy-middleware');

const proxy = createProxyMiddleware({
  /**
   * Fix bodyParser
   **/
  onProxyReq: fixRequestBody,
});

Intercept and manipulate responses

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.

Example:

const { createProxyMiddleware, responseInterceptor } = require('http-proxy-middleware');

const proxy = createProxyMiddleware({
  /**
   * IMPORTANT: avoid res.end being called automatically
   **/
  selfHandleResponse: true, // res.end() will be called internally by responseInterceptor()

  /**
   * Intercept response and replace 'Hello' with 'Goodbye'
   **/
  onProxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
    const response = responseBuffer.toString('utf8'); // convert buffer to string
    return response.replace('Hello', 'Goodbye'); // manipulate response and return the result
  }),
});

Check out interception recipes for more examples.

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-2021 Steven Chim

Apache/2.4.38 (Debian) Server at www.karls.computer Port 80