Registry / http-networking / koa-proxy

koa-proxy

JSON →
library1.0.0-alpha.3jsnpmunverified

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.

http-networkingweb-framework
npm install koa-proxy
github ↗package ↗
INSTALL
IMPORT
SIG · KOA-PROXY
K
koa-proxy
http-networkingjavascriptv1.0.0-alpha.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

proxy
✓ const proxy = require('koa-proxy');
✗ import proxy from '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
✓ const Koa = require('koa'); const app = new Koa();
✗ import Koa from 'koa';
Koa itself, in versions compatible with this middleware (Koa 2.x), is typically imported using CommonJS `require`.

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'); });
Debug
Known issues
breakingThis 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`).
affects: >=1.0.0-alpha.3
breakingBuilt 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.
affects: >=1.0.0-alpha.3
gotchaThe `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`.
affects: >=1.0.0-alpha.3
gotchaBy 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 }));`
affects: >=1.0.0-alpha.3
gotchaThe `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']`.
affects: >=1.0.0-alpha.3
Errors
Common errors & fixes
TypeError: app.use is not a function
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.
Proxy is not redirecting requests as expected or some requests are unexpectedly proxied.
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.
Session data or authentication fails after proxying, even though requests seem to go through.
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 }));`
Headers expected from the upstream server (e.g., 'Set-Cookie', 'Cache-Control') are missing in the client response.
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.
Upgrade
Version history
1.0.0-alpha.3latest on npm
Audit
Dependencies
koarequiredRequired peer dependency for the middleware to function within a Koa application (specifically Koa 2.x).
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/edorivai/koa-proxy ↗
packagehttps://www.npmjs.com/package/koa-proxy ↗
koa-proxy — npm install koa-proxy · libregistry