koa-http2-proxy

0.0.4 verified Sat Apr 25 auth: no javascript

A middleware for Koa that configures http2-proxy to reverse-proxy HTTP/HTTPS/WebSocket requests with minimal setup. Version 0.0.4 (latest) provides context matching via path strings or glob patterns, path rewriting, virtual host routing, and WebSocket support. It is a fork of http-proxy-middleware adapted for Koa's async middleware pattern and HTTP/2. Lightweight alternative to koa-proxies or koa-proxy, with similar API to http-proxy-middleware but natively async. Release cadence is low; no updates since 2022.

Common errors

error Error: Cannot find module 'koa-http2-proxy' ↓

cause Package not installed or path incorrect.

fix

Run npm install koa-http2-proxy and ensure require path is correct.

error TypeError: proxy is not a function ↓

cause Using ES import syntax (import) instead of require.

fix

Change from import proxy from 'koa-http2-proxy' to const proxy = require('koa-http2-proxy').

error Error: listen EADDRINUSE :::3000 ↓

cause Port 3000 already in use.

fix

Use a different port or kill the process using port 3000: kill $(lsof -t -i:3000).

Warnings

gotcha The package does not support ES modules (ESM). require() is the only import method. ↓

fix Use CommonJS require() or configure your bundler to handle CJS dependencies.

gotcha No TypeScript type definitions included; TypeScript users will need to define their own types or use @ts-ignore. ↓

fix Create a declaration file (e.g., koa-http2-proxy.d.ts) or use @ts-ignore.

gotcha WebSocket proxying requires manual upgrade handling via server.on('upgrade') because Koa does not handle WebSocket upgrades automatically. ↓

fix Implement a custom upgrade handler using the proxy.ws method: server.on('upgrade', proxy.upgrade).

Install

npm install koa-http2-proxy

yarn add koa-http2-proxy

pnpm add koa-http2-proxy

Imports

default
wrong
```
import proxy from 'koa-http2-proxy';
```
correct
```
const proxy = require('koa-http2-proxy');
```
This package does not ship ESM; use CommonJS require. There is no default ES import.

proxy function

wrong

const { proxy } = require('koa-http2-proxy');

correct

import proxy from 'koa-http2-proxy'; // use with bundler that supports CJS interop

The module exports a single function as default; named destructuring fails.

TypeScript types

wrong

import proxy from 'koa-http2-proxy'; // types missing

correct

// @ts-ignore
import proxy from 'koa-http2-proxy';

No TypeScript declarations included; use @ts-ignore or create custom .d.ts.

Quickstart

Creates a Koa app that proxies all requests to httpbin.org with changeOrigin true for virtual hosting.

const Koa = require('koa');
const proxy = require('koa-http2-proxy');
const app = new Koa();

app.use(proxy({ target: 'http://httpbin.org', changeOrigin: true }));

app.listen(3000, () => {
  console.log('Proxy server running on http://localhost:3000');
  console.log('Try: curl http://localhost:3000/ip => httpbin.org/ip');
});