Registry / http-networking / koa-better-http-proxy

koa-better-http-proxy

library0.2.10jsnpmunverified

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.

http-networking web-framework

npm install koa-better-http-proxy

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-BETTER-HTTP-PR

koa-better-http-proxy

http-networkingjavascriptv0.2.10

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

✓ import proxy from 'koa-better-http-proxy';

✗ import { proxy } from 'koa-better-http-proxy';

The main proxy function is a default export.

proxy

✓ const proxy = require('koa-better-http-proxy');

✗ const { proxy } = require('koa-better-http-proxy');

CommonJS `require` for the default export.

ProxyOptions

✓ import type { ProxyOptions, Context } from 'koa-better-http-proxy';

Import types for options and Koa Context when using TypeScript. Types were added in v0.2.2.

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`.

import Koa from 'koa'; import proxy from 'koa-better-http-proxy'; import Router from '@koa/router'; import { URL } from 'url'; const app = new Koa(); const router = new Router(); router.all('/api/(.*)', proxy('httpbin.org', { port: 80, https: false, proxyReqPathResolver: (ctx) => { const url = new URL(ctx.url, `http://${ctx.host}`); console.log(`Proxying request path: ${url.pathname}${url.search}`); return `/anything${url.pathname.substring('/api'.length)}${url.search}`; }, userResDecorator: (proxyRes, proxyResData, ctx) => { const data = JSON.parse(proxyResData.toString('utf8')); data.proxiedBy = 'koa-better-http-proxy'; data.originalUrl = ctx.url; return JSON.stringify(data); } })); app.use(router.routes()); app.use(router.allowedMethods()); app.listen(3000, () => { console.log('Koa proxy server listening on port 3000'); console.log('Try: curl http://localhost:3000/api/my-test?q=hello'); });

Debug

Known issues

breakingThe `memoizeHost` option was removed as it was never truly supported. Code relying on this option will break.

fix

Remove the `memoizeHost` option from your proxy configuration. There is no direct replacement as its functionality was not viable.

affects: >=0.2.0

breakingHeaders could leak across requests in certain scenarios, leading to incorrect or unintended behavior for subsequent requests using the same proxy instance.

fix

Upgrade to version 0.2.9 or higher to receive the fix for header isolation.

affects: <0.2.9

gotchaThe `proxyReqOptDecorator` function does not allow modification of the request path. Attempts to change the path within this decorator will not take effect.

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.

affects: >=0.2.8

gotchaBy 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.

fix

If `Connection: close` is required, manually add it using the `headers` option or `proxyReqOptDecorator`: `headers: { 'Connection': 'close' }`.

affects: >=0.2.7

gotchaThe `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'.

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.

affects: all

Errors

Common errors & fixes

TypeError: proxy is not a function

Incorrect import statement for the default export.

fix

For ES Modules, use `import proxy from 'koa-better-http-proxy';`. For CommonJS, use `const proxy = require('koa-better-http-proxy');`.

TypeError: app.use is not a function

Koa application instance is not correctly initialized or the middleware is being applied to a non-Koa object.

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`).

Property 'ctx' does not exist on type 'Context'.

Using an outdated or incompatible TypeScript type definition for Koa's Context object, or a version mismatch between Koa and the proxy types.

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.

Error: Cannot find module 'koa'

The `koa` package is not installed as a dependency in the project.

fix

Install Koa: `npm install koa` or `yarn add koa`.

Upgrade

Version history

0.2.10latest on npm

Audit

Dependencies

koarequiredRequired peer dependency for Koa middleware functionality.

Agent activity

3 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/nsimmons/koa-better-http-proxy ↗

packagehttps://www.npmjs.com/package/koa-better-http-proxy ↗