{"id":17758,"library":"koa-server-http-proxy","title":"Koa HTTP Proxy Middleware","description":"This package provides HTTP proxying capabilities for Koa 2 applications, serving as a middleware wrapper around the widely used `http-proxy-middleware` library. It enables developers to configure reverse proxies for routing requests to different target servers, perform path rewriting, and manage `changeOrigin` headers, which are common requirements for API gateways, development proxies, or microservice architectures. The library is currently at version 0.1.0 and has not seen any updates since its initial release in 2017, indicating it is no longer actively maintained. Its core proxying logic and options are derived directly from the underlying `http-proxy-middleware` dependency.","status":"abandoned","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/eugeneCN/koa-server-http-proxy","tags":["javascript","koa","koa-proxy","koa-http-proxy","koa-http-proxy-middleware"],"install":[{"cmd":"npm install koa-server-http-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add koa-server-http-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-server-http-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the web framework for this middleware.","package":"koa","optional":false},{"reason":"Provides the core HTTP proxying logic and options.","package":"http-proxy-middleware","optional":false}],"imports":[{"note":"This package primarily supports CommonJS syntax as it was published in 2017 (v0.1.0) and has not been updated since. ESM is not officially supported.","symbol":"proxy","correct":"const proxy = require('koa-server-http-proxy')"}],"quickstart":{"code":"const Koa = require('koa')\nconst app = new Koa()\nconst proxy = require('koa-server-http-proxy')\n\n// Proxy all /api requests to https://news-at.zhihu.com\napp.use(proxy('/api', {\n  target: 'https://news-at.zhihu.com',\n  pathRewrite: { '^/api': 'api/4/' }, // Rewrites /api/themes to api/4/themes\n  changeOrigin: true // Changes the origin header to the target URL\n}))\n\n// Example of multiple proxy targets\nconst proxyTable = {\n  '/json': {\n    target: 'http://jsonplaceholder.typicode.com',\n    pathRewrite: { '^/json': '' }, // Rewrites /json/posts to /posts\n    changeOrigin: true\n  },\n  '/another-api': {\n    target: 'https://api.example.com',\n    changeOrigin: true\n  }\n}\n\nObject.keys(proxyTable).forEach((context) => {\n  const options = proxyTable[context]\n  app.use(proxy(context, options))\n})\n\napp.listen(3000, () => {\n  console.log('Koa proxy server listening on port 3000')\n  console.log('Try: http://127.0.0.1:3000/api/themes')\n  console.log('Try: http://127.0.0.1:3000/json/posts/1')\n})\n","lang":"javascript","description":"Demonstrates setting up a basic HTTP proxy for a Koa application, showing single and multiple target configurations with path rewriting."},"warnings":[{"fix":"Migrate to actively maintained Koa proxy middleware solutions like `koa-proxies` (uses `http-proxy-middleware` v2.x/v3.x) or `@whitetrefoil/koa-http-proxy` (uses `node-http-proxy` directly).","message":"The package `koa-server-http-proxy` is considered abandoned. It has not been updated since its initial release (v0.1.0) in 2017. Using an unmaintained package can lead to security vulnerabilities, compatibility issues with newer Koa or Node.js versions, and a lack of support for modern web standards.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Consult the documentation for `http-proxy-middleware` version `0.17.4` specifically, or, preferably, migrate to a more current Koa proxy solution that uses a recent `http-proxy-middleware` version.","message":"This package relies on an outdated version of `http-proxy-middleware` (specifically `0.17.4`). The `http-proxy-middleware` library has undergone significant API changes and improvements, with current stable versions being v3.x. The options and behavior described in modern `http-proxy-middleware` documentation may not apply to this `koa-server-http-proxy` wrapper.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure that `koa-server-http-proxy` (or any proxy middleware) is applied before any middleware that consumes the request body, such as `koa-bodyparser` or `koa-body`. Process the body *after* the proxy has decided not to handle the request, or use `responseInterceptor` in modern `http-proxy-middleware` to handle bodies after proxying.","message":"Using `body-parser` or similar middleware before the proxy middleware can cause requests with a body (e.g., POST requests) to hang or behave unexpectedly. The `http-proxy-middleware` (and its underlying `node-http-proxy`) expects to read the request stream directly.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure that Koa's context (`ctx.respond = false`) is correctly managed if the proxy middleware is intended to fully handle the response, preventing Koa from attempting to send its own headers. Check for other middleware that might be sending responses prematurely. Sometimes, older proxy libraries have specific workarounds for Koa's `res.end()` behavior.","cause":"This error typically occurs in Koa when middleware attempts to modify headers after a response has already been sent to the client. Proxy middleware can sometimes prematurely send a response or interfere with Koa's default response handling.","error":"Error: Can't set headers after they are sent."},{"fix":"Ensure `changeOrigin: true` is set in the proxy options to correctly set the `Host` header of the proxy request to the target's host. If the target API still requires specific CORS headers, you may need to add `proxyRes` event listeners to modify the response headers coming *from* the proxied server before they reach the client, or configure CORS on the target API itself if possible.","cause":"Cross-Origin Resource Sharing (CORS) errors occur when a browser-based client tries to make a request to a different origin (domain, protocol, or port) than the one it originated from, and the server does not explicitly allow it. While a proxy often bypasses this for the *client*, the proxy *itself* must correctly forward or modify headers if the target API has CORS restrictions.","error":"CORS policy: No 'Access-Control-Allow-Origin' header is present"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}