Koa Proxy Middleware

1.0.0-alpha.3 verified Thu Apr 23 auth: no javascript abandoned

koa-proxy is an unmaintained proxy middleware specifically designed for Koa 2.x applications. It allows developers to proxy HTTP requests to a different host or URL, offering features like path mapping, regular expression-based matching for selective proxying, and control over request/response headers and cookie forwarding. Given its `1.0.0-alpha.3` version and last update several years ago, it is considered abandoned. This package predates modern JavaScript features like `async/await` and ESM, focusing on a synchronous middleware pattern and CommonJS module system. Its core functionality enables simple URL redirection and content serving from external sources within a Koa server.

Common errors

error TypeError: app.use is not a function ↓

cause Using an outdated Koa application instance (Koa 1.x) or incorrectly initialized Koa app with this middleware, which expects Koa 2.x.

fix

Ensure you are using Koa 2.x or later and have initialized app = new Koa(); correctly. This error can also occur if koa is not properly installed or required.

error Proxy is not redirecting requests as expected or some requests are unexpectedly proxied. ↓

cause Incorrect configuration of the `match` regular expression or the `map` function, leading to unintended routing behavior.

fix

Carefully review and test your match regex and map function. Use console logs within the map function to see the path argument and its return value. Verify the regex logic with an online tool.

error Session data or authentication fails after proxying, even though requests seem to go through. ↓

cause Cookies from the client are not being forwarded to the upstream server, leading to a loss of session state.

fix

Set jar: true in your proxy configuration to enable forwarding of client cookies to the target host: app.use(proxy({ host: '...', jar: true }));

error Headers expected from the upstream server (e.g., 'Set-Cookie', 'Cache-Control') are missing in the client response. ↓

cause The `suppressResponseHeaders` option is configured to remove certain headers from the proxy's response.

fix

Check your suppressResponseHeaders array and ensure it does not include headers you intend to pass through. Remember that matching is case-insensitive.

Warnings

breaking This package is considered abandoned and has not been updated in several years (last publish 8 years ago). It may contain unpatched security vulnerabilities and is not recommended for new projects or production use. ↓

fix Migrate to a actively maintained Koa proxy middleware like `koa-proxies`, `@koa/proxy`, or `http-proxy-middleware` (if used with `koa-connect`).

breaking Built for Koa 2.x (generator-based or early async/await middleware), this middleware may not be fully compatible with newer Koa versions (e.g., Koa 3+) and their evolved async/await context handling. ↓

fix If migrating, ensure your Koa application is also on a compatible version (Koa 2.x) or use a modern proxy solution designed for current Koa versions.

gotcha The `match` option uses regular expressions. If not configured carefully, it might inadvertently proxy requests you did not intend or fail to proxy requests you did intend. ↓

fix Thoroughly test `match` regex patterns. Use online regex testers to validate behavior before deployment. For example, `match: /^\/api\//` proxies `/api/foo` but not `/foo/api`.

gotcha By default, `koa-proxy` does not forward cookies to the upstream server. This can lead to unexpected session issues or authentication failures if the target server relies on cookies. ↓

fix Enable cookie forwarding by setting the `jar` option to `true` in the proxy configuration: `app.use(proxy({ host: '...', jar: true }));`

gotcha The `suppressRequestHeaders` and `suppressResponseHeaders` options perform case-insensitive matching. If you're removing headers, be aware that slight variations in case (e.g., 'Content-Type' vs 'content-type') will all be suppressed if matched. ↓

fix Be explicit with header names, or test thoroughly to ensure the correct headers are suppressed without unintended side effects. For example, `['authorization', 'cookie']`.

Install

npm install koa-proxy

yarn add koa-proxy

pnpm add koa-proxy

Imports

proxy
wrong
```
import proxy from 'koa-proxy';
```
correct
```
const proxy = require('koa-proxy');
```
This package is a CommonJS module and does not support ES modules directly. Attempting to use `import` syntax will result in errors.
ProxyOptions
```
/** @type {import('koa-proxy').ProxyOptions} */
```
While this package has limited type definitions, JSDoc can provide basic type hinting for configuration objects in JavaScript files.
KoaApp
wrong
```
import Koa from 'koa';
```
correct
```
const Koa = require('koa');
const app = new Koa();
```
Koa itself, in versions compatible with this middleware (Koa 2.x), is typically imported using CommonJS `require`.

Quickstart

Demonstrates basic usage of koa-proxy to forward requests, including path matching, URL remapping, and header/cookie forwarding options.

const Koa = require('koa');
const proxy = require('koa-proxy');
const app = new Koa();

// Basic proxying: requests to your server will be forwarded to 'http://example.com'
// e.g., GET /api/users on localhost:3000 -> GET /api/users on http://example.com
app.use(proxy({
  host: 'http://example.com', // The target host for all proxied requests
  match: /\/api\/.* / // Only proxy requests starting with /api/
}));

// Example of proxying a specific path with remapping and custom headers
app.use(proxy({
  host: 'http://cdn.someplace.net',
  match: /^\/static\/(.*)/, // Match /static/ and capture the rest of the path
  map: function(path) { // Remap /static/foo.js to /assets/foo.js on the CDN
    return path.replace('/static/', '/assets/');
  },
  overrideRequestHeaders: {
    'X-Custom-Header': 'Proxy-Request'
  },
  jar: true // Forward cookies to the target host
}));

app.listen(3000, () => {
  console.log('Koa proxy server listening on port 3000');
  console.log('Try accessing http://localhost:3000/api/data or http://localhost:3000/static/image.png');
});