{"id":16839,"library":"koa-better-http-proxy","title":"Koa Better HTTP Proxy","description":"koa-better-http-proxy is an HTTP proxy middleware for Koa applications, enabling requests to be forwarded to a different host and the response passed back to the client. The current stable version is 0.2.10. This package has a moderate release cadence, with several minor updates and bug fixes released within the last year, indicating active maintenance. Key differentiators include its foundation on `express-http-proxy`, support for asynchronous path resolvers (`proxyReqPathResolver`) and response/header decorators (`userResDecorator`, `userResHeadersDecorator`), and automatic handling of gzipped responses. It provides fine-grained control over request and response modification, header stripping, and custom `http.Agent` usage, making it suitable for complex proxying scenarios within a Koa ecosystem.","status":"active","version":"0.2.10","language":"javascript","source_language":"en","source_url":"git://github.com/nsimmons/koa-better-http-proxy","tags":["javascript","koa-better-http-proxy","typescript"],"install":[{"cmd":"npm install koa-better-http-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add koa-better-http-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-better-http-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Koa middleware functionality.","package":"koa","optional":false}],"imports":[{"note":"The main proxy function is a default export.","wrong":"import { proxy } from 'koa-better-http-proxy';","symbol":"proxy","correct":"import proxy from 'koa-better-http-proxy';"},{"note":"CommonJS `require` for the default export.","wrong":"const { proxy } = require('koa-better-http-proxy');","symbol":"proxy","correct":"const proxy = require('koa-better-http-proxy');"},{"note":"Import types for options and Koa Context when using TypeScript. Types were added in v0.2.2.","symbol":"ProxyOptions","correct":"import type { ProxyOptions, Context } from 'koa-better-http-proxy';"}],"quickstart":{"code":"import Koa from 'koa';\nimport proxy from 'koa-better-http-proxy';\nimport Router from '@koa/router';\nimport { URL } from 'url';\n\nconst app = new Koa();\nconst router = new Router();\n\nrouter.all('/api/(.*)', proxy('httpbin.org', {\n  port: 80,\n  https: false,\n  proxyReqPathResolver: (ctx) => {\n    const url = new URL(ctx.url, `http://${ctx.host}`);\n    console.log(`Proxying request path: ${url.pathname}${url.search}`);\n    return `/anything${url.pathname.substring('/api'.length)}${url.search}`;\n  },\n  userResDecorator: (proxyRes, proxyResData, ctx) => {\n    const data = JSON.parse(proxyResData.toString('utf8'));\n    data.proxiedBy = 'koa-better-http-proxy';\n    data.originalUrl = ctx.url;\n    return JSON.stringify(data);\n  }\n}));\n\napp.use(router.routes());\napp.use(router.allowedMethods());\n\napp.listen(3000, () => {\n  console.log('Koa proxy server listening on port 3000');\n  console.log('Try: curl http://localhost:3000/api/my-test?q=hello');\n});","lang":"typescript","description":"This example sets up a Koa server with `koa-better-http-proxy` to proxy requests starting with `/api` to `httpbin.org/anything`. It demonstrates path rewriting using `proxyReqPathResolver` and modifying the response body with `userResDecorator`."},"warnings":[{"fix":"Remove the `memoizeHost` option from your proxy configuration. There is no direct replacement as its functionality was not viable.","message":"The `memoizeHost` option was removed as it was never truly supported. Code relying on this option will break.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Upgrade to version 0.2.9 or higher to receive the fix for header isolation.","message":"Headers could leak across requests in certain scenarios, leading to incorrect or unintended behavior for subsequent requests using the same proxy instance.","severity":"breaking","affected_versions":"<0.2.9"},{"fix":"Use the `proxyReqPathResolver` option to modify the request path before it is sent to the proxied host. `proxyReqOptDecorator` is intended for modifying other request options like headers or agent settings.","message":"The `proxyReqOptDecorator` function does not allow modification of the request path. Attempts to change the path within this decorator will not take effect.","severity":"gotcha","affected_versions":">=0.2.8"},{"fix":"If `Connection: close` is required, manually add it using the `headers` option or `proxyReqOptDecorator`: `headers: { 'Connection': 'close' }`.","message":"By default, `Connection: close` is no longer set on proxy requests. If your backend relies on this header for specific connection management, its absence might alter behavior.","severity":"gotcha","affected_versions":">=0.2.7"},{"fix":"Avoid mutating `proxyRes` or `ctx` directly within decorators. Rely on dedicated options or hooks for header modification when they become available to ensure future compatibility. Focus `userResDecorator` on modifying response data and `userResHeadersDecorator` on modifying headers.","message":"The `userResDecorator` and `userResHeadersDecorator` functions pass `proxyRes` and `ctx` by reference. While this *can* be exploited to modify response headers directly, it is not a stable API and future releases may remove this 'exploit'.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import proxy from 'koa-better-http-proxy';`. For CommonJS, use `const proxy = require('koa-better-http-proxy');`.","cause":"Incorrect import statement for the default export.","error":"TypeError: proxy is not a function"},{"fix":"Ensure you have `import Koa from 'koa';` and `const app = new Koa();` at the start of your Koa application setup, and that `koa` is installed (`npm install koa`).","cause":"Koa application instance is not correctly initialized or the middleware is being applied to a non-Koa object.","error":"TypeError: app.use is not a function"},{"fix":"Ensure `koa-better-http-proxy` is at least v0.2.2 for TypeScript types, and that `koa` and `@types/koa` are correctly installed and aligned with your Koa version. Sometimes, reinstalling `@types/koa` can resolve such issues.","cause":"Using an outdated or incompatible TypeScript type definition for Koa's Context object, or a version mismatch between Koa and the proxy types.","error":"Property 'ctx' does not exist on type 'Context'."},{"fix":"Install Koa: `npm install koa` or `yarn add koa`.","cause":"The `koa` package is not installed as a dependency in the project.","error":"Error: Cannot find module 'koa'"}],"ecosystem":"npm","meta_description":null}