http-proxy-middleware

http-proxy-middleware gives Node.js servers a single createProxyMiddleware() call to forward HTTP and WebSocket traffic to another host. It targets Express, Connect, Next.js, Hono, Polka, and any framework that accepts a standard request-handler signature, making it the standard building block for local API proxying, reverse-proxy gateways, and framework dev-server integrations (it powers webpack-dev-server’s and Vite’s proxy option under the hood).

Under the hood it is a thin, well-typed orchestration layer over httpxy (a maintained fork of the venerable http-proxy), adding the pieces application developers actually need day to day: path-based filtering so only matching requests get proxied, path rewriting to strip or remap URL prefixes before forwarding, a router for picking a target dynamically per-request (by host, path, or custom function), and a plugin system for hooking into proxy lifecycle events like proxyReq/proxyRes.

The library has been maintained continuously since 2015, moved fully to TypeScript, and ships first-class WebSocket upgrade handling, response-body interception, and graceful shutdown behavior — the kind of edge cases that come from a decade of production usage rather than a fresh rewrite.

What You Get

• createProxyMiddleware() — a single factory function returning a request handler compatible with Express, Connect, Polka, and any Node HTTP framework
• Path filtering via exact prefixes, glob patterns (micromatch), arrays of paths, or a fully custom matcher function
• Path rewriting (pathRewrite) to strip, remap, or dynamically transform the forwarded URL, including async rewrite functions
• Dynamic target routing (router) keyed by host, path, host+path, or a custom async function that resolves the target per-request
• Built-in WebSocket upgrade proxying with automatic subscription to the underlying HTTP server’s upgrade event
• A plugin system (definePlugin, ejectPlugins) exposing hooks into proxy lifecycle events for logging, error handling, and custom behavior
• responseInterceptor() helper for buffering and rewriting proxied response bodies before they reach the client
• First-class TypeScript types plus a dedicated http-proxy-middleware/hono entry point for Hono’s request/response model

Common Use Cases

• Local development: proxying a frontend dev server’s /api calls to a separately-running backend to avoid CORS
• API gateway: routing incoming requests to different backend services based on path or host
• Framework dev-server proxying: the option other tools (webpack-dev-server, Vite-adjacent setups) expose under the hood
• WebSocket proxying for real-time apps that need both HTTP and ws:// traffic forwarded to the same backend
• Response rewriting: intercepting and modifying a proxied response body (e.g., replacing text or injecting headers) before it’s sent to the client

Under The Hood

Architecture

The library is organized as a thin orchestration class, HttpProxyMiddleware (src/http-proxy-middleware.ts), which wraps an httpxy proxy server instance. createProxyMiddleware() (src/factory.ts) is the only public entry point most consumers touch — it constructs the class and returns its bound middleware request handler. Each incoming request runs through shouldProxy() (src/path-filter.ts) to decide whether to forward it, then prepareProxyRequest() applies router (src/router.ts) and pathRewrite (src/path-rewriter.ts) in a fixed order — router resolves the target against the original path, and only afterward is the path itself rewritten — before delegating to httpxy’s proxy.web()/proxy.ws(). WebSocket support is layered on by subscribing to the underlying HTTP server’s native upgrade event exactly once per server instance (tracked via a WeakSet), and graceful shutdown is handled by counting active servers and closing the shared proxy only when the last one closes. Error handling bridges a real inconsistency in httpxy’s promise-based API: missing-target errors surface via an ‘error’ event but return a boolean (so the code manually throws), while network errors during proxy.web() reject without emitting ‘error’ (so the code manually re-emits it) — a documented workaround visible directly in the source as [Smoking Gun] comments.

Tech Stack

Written in TypeScript with type: module (ESM-only), depending on httpxy (the actively maintained fork of http-proxy that this package is built around), micromatch/is-glob for glob-pattern path matching, is-plain-obj for router-table detection, and debug for namespaced diagnostic logging. It targets modern Node.js (^22.15.0 || ^24.0.0 || >=26.0.0 in engines), builds via tsc --build, lints/formats with ESLint 10 plus oxfmt, and runs on Vitest. Dev dependencies bring in express, hono, supertest, mockttp, msw, and nock purely to exercise real integration scenarios against each supported framework.

Code Quality

The repo has a large, framework-real test suite split into test/unit (path filtering, path rewriting, router, plugin loading, response interceptor, config validation, logging) and test/e2e (dedicated spec files per integration target: Express, Express error middleware, HTTP/2, WebSockets, Hono, nock, msw, IPv6, Unix domain sockets, graceful shutdown), run through Vitest with coverage. Error handling is explicit and typed via a custom HttpProxyMiddlewareError class carrying stable error codes (e.g. ERR_CONFIG_FACTORY_TARGET_MISSING) rather than opaque thrown strings. CI runs via GitHub Actions with status badges for build and Coveralls coverage, plus Husky/lint-staged pre-commit hooks and a cspell spellcheck script — the toolchain of an actively-governed, decade-old library rather than a quick utility.

What Makes It Unique

Rather than reimplementing proxying from scratch, it deliberately positions itself as an ergonomics layer over httpxy/http-proxy, adding the specific things application developers repeatedly hand-roll around a raw proxy — path filtering, path rewriting, dynamic per-request routing, and a typed plugin/event system — while explicitly working around known inconsistencies in the underlying proxy engine’s error semantics so consumers get consistent next(err) behavior in Express regardless of whether the failure is a bad config or a network error. Its longevity (a decade of continuous maintenance and adoption as the proxy layer inside other build tools) is itself the differentiator: the edge cases it handles (IPv6 literal targets, WebSocket upgrade subscription lifecycle, HTTP/2 servers, Unix domain sockets) come from real-world usage rather than being anticipated in a fresh design.