{"id":17753,"library":"koa-proxy","title":"Koa Proxy Middleware","description":"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.","status":"abandoned","version":"1.0.0-alpha.3","language":"javascript","source_language":"en","source_url":"https://github.com/edorivai/koa-proxy","tags":["javascript","koa","middleware","proxy"],"install":[{"cmd":"npm install koa-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add koa-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the middleware to function within a Koa application (specifically Koa 2.x).","package":"koa","optional":false}],"imports":[{"note":"This package is a CommonJS module and does not support ES modules directly. Attempting to use `import` syntax will result in errors.","wrong":"import proxy from 'koa-proxy';","symbol":"proxy","correct":"const proxy = require('koa-proxy');"},{"note":"While this package has limited type definitions, JSDoc can provide basic type hinting for configuration objects in JavaScript files.","symbol":"ProxyOptions","correct":"/** @type {import('koa-proxy').ProxyOptions} */"},{"note":"Koa itself, in versions compatible with this middleware (Koa 2.x), is typically imported using CommonJS `require`.","wrong":"import Koa from 'koa';","symbol":"KoaApp","correct":"const Koa = require('koa');\nconst app = new Koa();"}],"quickstart":{"code":"const Koa = require('koa');\nconst proxy = require('koa-proxy');\nconst app = new Koa();\n\n// Basic proxying: requests to your server will be forwarded to 'http://example.com'\n// e.g., GET /api/users on localhost:3000 -> GET /api/users on http://example.com\napp.use(proxy({\n  host: 'http://example.com', // The target host for all proxied requests\n  match: /\\/api\\/.* / // Only proxy requests starting with /api/\n}));\n\n// Example of proxying a specific path with remapping and custom headers\napp.use(proxy({\n  host: 'http://cdn.someplace.net',\n  match: /^\\/static\\/(.*)/, // Match /static/ and capture the rest of the path\n  map: function(path) { // Remap /static/foo.js to /assets/foo.js on the CDN\n    return path.replace('/static/', '/assets/');\n  },\n  overrideRequestHeaders: {\n    'X-Custom-Header': 'Proxy-Request'\n  },\n  jar: true // Forward cookies to the target host\n}));\n\napp.listen(3000, () => {\n  console.log('Koa proxy server listening on port 3000');\n  console.log('Try accessing http://localhost:3000/api/data or http://localhost:3000/static/image.png');\n});","lang":"javascript","description":"Demonstrates basic usage of koa-proxy to forward requests, including path matching, URL remapping, and header/cookie forwarding options."},"warnings":[{"fix":"Migrate to a actively maintained Koa proxy middleware like `koa-proxies`, `@koa/proxy`, or `http-proxy-middleware` (if used with `koa-connect`).","message":"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.","severity":"breaking","affected_versions":">=1.0.0-alpha.3"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0-alpha.3"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.3"},{"fix":"Enable cookie forwarding by setting the `jar` option to `true` in the proxy configuration: `app.use(proxy({ host: '...', jar: true }));`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.3"},{"fix":"Be explicit with header names, or test thoroughly to ensure the correct headers are suppressed without unintended side effects. For example, `['authorization', 'cookie']`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.3"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"Using an outdated Koa application instance (Koa 1.x) or incorrectly initialized Koa app with this middleware, which expects Koa 2.x.","error":"TypeError: app.use is not a function"},{"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.","cause":"Incorrect configuration of the `match` regular expression or the `map` function, leading to unintended routing behavior.","error":"Proxy is not redirecting requests as expected or some requests are unexpectedly proxied."},{"fix":"Set `jar: true` in your proxy configuration to enable forwarding of client cookies to the target host: `app.use(proxy({ host: '...', jar: true }));`","cause":"Cookies from the client are not being forwarded to the upstream server, leading to a loss of session state.","error":"Session data or authentication fails after proxying, even though requests seem to go through."},{"fix":"Check your `suppressResponseHeaders` array and ensure it does not include headers you intend to pass through. Remember that matching is case-insensitive.","cause":"The `suppressResponseHeaders` option is configured to remove certain headers from the proxy's response.","error":"Headers expected from the upstream server (e.g., 'Set-Cookie', 'Cache-Control') are missing in the client response."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}