koa2-nginx

Proxy middleware for koa2 based on http-proxy-middleware wrapper and support for configuring multiple proxy rules. The way to use is inspired by the proxy option of webpack-dev-server

TL;DR

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

1var koa = require('koa');
2var proxy = require('koa2-nginx');
3
4var app = koa();
5
6app.use(
7  proxy({ '/api': { target: 'http://www.example.com', changeOrigin: true } })
8);
9app.listen(3000);
10
11// http://localhost:3000/api/v1 -> http://www.example.com/api/v1

All http-proxy-middleware options can be used.

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

Breaking with koa2-nginx@1.x

• V2.x version is a fully refactored version
• V1.x version is based on http-proxy, and the v2 version provides more rich and reasonable configuration based on http-proxy-middleware.
• The logic for internally processing context-length is removed, and we think this should be handled by the developer itself in the events hooks.

Table of Contents

• Install
• Example
• Options
• Usage
• Working examples
• FAQ

Install

1$ npm i koa2-nginx

Example

An example with koa2 server.

1// include dependencies
2const Koa = require('koa');
3const proxy = require('koa2-nginx');
4
5// proxy middleware options
6const options = {
7  '/api': {
8    target: 'http://www.example.com', 
9    changeOrigin: true,
10  },
11  '**/*.html': {
12    target: 'http://www.example2.com', 
13    changeOrigin: true
14  },
15  '/user': 'http://localhost:3000'
16};
17
18// create the proxy (without context)
19const exampleProxy = proxy(options);
20
21// mount `exampleProxy` in web server
22const app = new Koa();
23app.use(exampleProxy);
24app.listen(3000);

Options

koa2-nginx options

• autoProcessReqBody: If koa2-nginx is behind the body-parser, it may cause the request body to fail to proxy. Set autoProcessReqBody to true can proxy the request body in json and form content-type.

http-proxy-middleware options

Can refer option to http-proxy-middleware for each forwarding rule.

http-proxy options

Can refer option to http-proxy for each forwarding rule.

Usage

Option supports multiple pattern-matching proxy

normal

1let option = {
2  '/api': {
3    target: 'http://www.example.com', 
4    changeOrigin: true,
5    onProxyRes(proxyRes, req, res) {
6      proxyRes.headers['x-added'] = 'foobar'; // add new header to response
7      delete proxyRes.headers['x-removed'];
8    },
9    onProxyReq(proxyReq, req, res) {
10      proxyReq.setHeader('x-added', 'foobar');
11    }
12  }
13}

function

1let option = {
2  '/api': function() {
3    // your custom logic
4    return {
5        target: 'http://www.example.com', 
6        changeOrigin: true,
7    }
8  }
9}

batch proxy

If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a context property:

1let option = [{
2    context: ['/auth', '/api'], target: 'http://localhost:3000'
3}]

Working examples

• EggJS TODO

FAQ

1. POST/PUT request body is not proxied to the servers #40 or set autoProcessReqBody to true