Koa HTTP Proxy Middleware

Common errors

• TypeError: ctx.request.body is undefined

  cause `koa-proxies` is placed after `koa-bodyparser` or a similar body-parsing middleware, causing the request stream to be consumed before `koa-proxies` can process it.
  fix Ensure `koa-proxies` middleware is always applied before any middleware that parses or consumes the request body, such as `koa-bodyparser`. For example: `app.use(proxy('/api', {...})); app.use(bodyParser());`

• Proxy error: connect ECONNREFUSED

  cause The target server specified in the `options.target` configuration is not running, is inaccessible, or is listening on a different address/port than configured.
  fix Verify that the backend service (e.g., `http://localhost:3001` in the quickstart) is actively running and reachable from the server hosting your Koa application. Check network configurations, firewall rules, or DNS settings if the target is remote.

• Error: Can't set headers after they are sent.

  cause This typically occurs when a proxy request fails, and an error handler attempts to send a response after the `http-proxy` library has already sent headers or a partial response.
  fix Implement robust error handling within the `options.events.error` callback. Before sending a response in the error handler, check `res.headersSent` to avoid attempting to set headers on an already-responded stream. For example: `if (!res.headersSent) { res.writeHead(500); res.end('Proxy error'); }`

Warnings

• gotcha Placing `koa-proxies` after `koa-bodyparser` (or any other middleware that consumes the request body stream) in the middleware chain can lead to requests hanging or unexpected behavior, especially for POST/PUT requests with bodies.
  Fix: Always ensure `app.use(proxy(...))` middleware is registered *before* `app.use(bodyParser())` or similar body-parsing middleware.
• breaking The internal path resolution logic was updated in `v0.9.0` to utilize the modern `URL` constructor instead of the deprecated Node.js `url.resolve` method.
  Fix: While this change is mostly internal, applications with highly customized `rewrite` functions or those performing complex URL manipulations should verify compatibility when upgrading from versions prior to 0.9.0.
• gotcha Prior to `v0.6.1`, there was a bug where `http-proxy` events (e.g., `error`, `proxyReq`, `proxyRes`) were registered multiple times, which could potentially lead to memory leaks or incorrect event handling logic.
  Fix: Upgrade to `v0.6.1` or later to ensure event listeners are correctly registered only once per proxy instance.

Install

• npm install koa-proxies npm
• yarn add koa-proxies yarn
• pnpm add koa-proxies pnpm

Imports

• proxy
  wrong:

  import { proxy } from 'koa-proxies';

  correct:

  import proxy from 'koa-proxies';

  The `proxy` function is the default export of the module, commonly used in ESM modules. Attempting to destructure it as a named import will result in `undefined`.
• proxy (CommonJS)

  const proxy = require('koa-proxies');

  For CommonJS environments, `require()` is the standard way to import the middleware. Attempting an ESM `import` in a CJS file will cause a syntax error.
• KoaProxyOptions
  wrong:

  import { KoaProxyOptions } } from 'koa-proxies';

  correct:

  import type { KoaProxyOptions } from 'koa-proxies';

  TypeScript types for `KoaProxyOptions` are available since v0.11.0. Use `import type` for type-only imports to prevent potential bundling issues in certain build setups.

Quickstart

Demonstrates basic and dynamic proxy configuration for a Koa application, including path rewriting, origin modification, custom logging, and path parameter handling.

import Koa from 'koa';
import proxy from 'koa-proxies';
import httpsProxyAgent from 'https-proxy-agent'; // Install if needed: npm i https-proxy-agent

const app = new Koa();

// Example 1: Basic proxy for a fixed path
app.use(proxy('/api', {
  target: 'http://localhost:3001', // Your target API server
  changeOrigin: true, // Changes the origin of the host header to the target URL
  rewrite: path => path.replace('/api', ''), // Rewrites the path from /api/users to /users
  logs: true // Enables logging of proxy requests to console
}));

// Example 2: Dynamic proxy with path parameters
app.use(proxy('/users/:id', (params, ctx) => {
  return {
    target: 'https://jsonplaceholder.typicode.com', // A public API for testing
    changeOrigin: true,
    rewrite: () => `/users/${params.id}`, // Dynamically rewrite path based on URL parameter
    logs: (ctx, target) => {
      console.log(`[Proxy Log] ${ctx.method} ${ctx.path} -> ${target}`);
    },
    // Example of using a proxy agent (install 'https-proxy-agent' if needed)
    // agent: new httpsProxyAgent('http://your.proxy.server:port') // Remove if not using a proxy agent
  };
}));

app.listen(3000, () => {
  console.log('Koa proxy server listening on http://localhost:3000');
  console.log('Try visiting http://localhost:3000/api/posts/1 (proxies to http://localhost:3001/posts/1)');
  console.log('Or http://localhost:3000/users/1 (proxies to https://jsonplaceholder.typicode.com/users/1)');
});