{"id":18481,"library":"koa2-proxy-middleware","title":"koa2-proxy-middleware","description":"A Koa2 middleware wrapping http-proxy-middleware to proxy requests based on URL patterns using path-to-regexp. Version 0.0.4 is the current stable release; the package is infrequently updated. It provides a declarative way to configure multiple proxy targets in Koa2 applications, leveraging the mature http-proxy-middleware for WebSocket and HTTP proxying. Unlike generic Koa proxy middlewares, it uses path-to-regexp for route matching, allowing dynamic route parameters. It ships TypeScript definitions.","status":"active","version":"0.0.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","koa2","proxy","http-proxy-middleware","typescript"],"install":[{"cmd":"npm install koa2-proxy-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add koa2-proxy-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa2-proxy-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core proxy functionality","package":"http-proxy-middleware","optional":false},{"reason":"Route pattern matching","package":"path-to-regexp","optional":false}],"imports":[{"note":"Package uses CommonJS; default export is a function. For TypeScript, use `import proxy = require('koa2-proxy-middleware')` or `import * as proxy from 'koa2-proxy-middleware'`.","wrong":"import proxy from 'koa2-proxy-middleware'","symbol":"default","correct":"const proxy = require('koa2-proxy-middleware')"},{"note":"If using ESM with moduleResolution node or bundler, default import works in TypeScript.","wrong":"","symbol":"default","correct":"import proxy from 'koa2-proxy-middleware'"},{"note":"TypeScript type export for the proxy function signature used in type annotations.","wrong":"","symbol":"ProxyMiddleware","correct":"import { ProxyMiddleware } from 'koa2-proxy-middleware'"}],"quickstart":{"code":"const Koa = require('koa');\nconst proxy = require('koa2-proxy-middleware');\nconst app = new Koa();\nconst options = {\n  targets: {\n    '/api/(.*)': {\n      target: 'http://httpbin.org',\n      changeOrigin: true,\n    },\n  },\n};\napp.use(proxy(options));\napp.listen(3000);\nconsole.log('Proxy server running on port 3000');","lang":"javascript","description":"Creates a Koa server that proxies all requests matching '/api/(.*)' to httpbin.org using the proxy middleware."},"warnings":[{"fix":"Use require() or configure module resolution to allow CommonJS.","message":"Package is CommonJS-only; cannot be imported as ESM in Node.js without bundler.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Ensure proxy middleware is used before koa-bodyparser or similar body parsers.","message":"Bodyparser middleware must be placed after proxy middleware for POST requests to avoid delays.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"No action needed unless you rely on specific regexp behavior.","message":"path-to-regexp v2 used internally; newer versions may have breaking changes.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Ensure patterns follow path-to-regexp syntax (e.g., '/:param', '/(.*)').","message":"Options key patterns are converted to regexp using path-to-regexp; non-standard patterns may not match as expected.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install koa2-proxy-middleware`.","cause":"Package not installed or not in node_modules.","error":"Cannot find module 'koa2-proxy-middleware'"},{"fix":"Use `const proxy = require('koa2-proxy-middleware')`.","cause":"Incorrect import style (e.g., destructured import when package exports a single function).","error":"TypeError: proxy is not a function"},{"fix":"Install http-proxy-middleware explicitly: `npm install http-proxy-middleware`.","cause":"Dependency not installed automatically when peer dependency.","error":"Error: Cannot find module 'http-proxy-middleware'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}