koa2-nginx

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

var koa = require('koa');
var proxy = require('koa2-nginx');

var app = koa();

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

// 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

$ npm i koa2-nginx

Example

An example with koa2 server.

// include dependencies
const Koa = require('koa');
const proxy = require('koa2-nginx');

// proxy middleware options
const options = {
  '/api': {
    target: 'http://www.example.com', 
    changeOrigin: true,
  },
  '**/*.html': {
    target: 'http://www.example2.com', 
    changeOrigin: true
  },
  '/user': 'http://localhost:3000'
};

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

// mount `exampleProxy` in web server
const app = new Koa();
app.use(exampleProxy);
app.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

let option = {
  '/api': {
    target: 'http://www.example.com', 
    changeOrigin: true,
    onProxyRes(proxyRes, req, res) {
      proxyRes.headers['x-added'] = 'foobar'; // add new header to response
      delete proxyRes.headers['x-removed'];
    },
    onProxyReq(proxyReq, req, res) {
      proxyReq.setHeader('x-added', 'foobar');
    }
  }
}

function

let option = {
  '/api': function() {
    // your custom logic
    return {
        target: 'http://www.example.com', 
        changeOrigin: true,
    }
  }
}

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:

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

Working examples

• EggJS TODO

FAQ

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