Registry / web-framework / koa-proxies

koa-proxies

JSON →
library0.12.4jsnpmunverified

`koa-proxies` is an HTTP proxy middleware specifically designed for Koa@2.x applications, providing robust proxying capabilities powered by the underlying `http-proxy` library. It enables developers to easily route incoming requests to different target servers, a common pattern for API forwarding, bypassing CORS restrictions during development, or orchestrating microservices. The library currently stands at version 0.12.4. While its latest release dates indicate a more maintenance-focused cadence rather than active feature development (last significant features around 2020), it remains a functional and widely used choice for Koa projects. Key differentiators include its flexible option handling, allowing both static configurations and dynamic determination of proxy settings via a function, and integrated support for `path-match` for advanced routing logic. It also provides built-in TypeScript type definitions since version 0.11.0, enhancing developer experience in TypeScript-based Koa applications.

npm install koa-proxies
INSTALL
IMPORT
SIG · KOA-PROXIES
K
koa-proxies
web-frameworkjavascriptv0.12.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

proxy
import proxy from 'koa-proxies';
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
import type { KoaProxyOptions } from 'koa-proxies';
import { 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.

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)'); });
Debug
Known issues
gotchaPlacing `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.
affects: >=0.5.0
breakingThe 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.
affects: >=0.9.0
gotchaPrior 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.
affects: <=0.6.0
Errors
Common errors & fixes
TypeError: ctx.request.body is undefined
`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
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.
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'); }`
Upgrade
Version history
0.12.4latest on npm
Audit
Dependencies
koarequiredPeer dependency required for the middleware to function within a Koa application.
Agent activity
12 hits · last 30 days
node
11
Amazon
1
Resources
koa-proxies — npm install koa-proxies · libregistry