http-proxy-middleware — Configurable Proxy Middleware for Node.js

Introduction

http-proxy-middleware wraps the powerful http-proxy library into a middleware function compatible with Express, Connect, Next.js, and Webpack Dev Server. It is the standard way to proxy API requests in Node.js development and production environments, solving CORS issues during local development and enabling microservice routing in production. Most React, Vue, and Angular CLI tools use it internally for their proxy configuration.

What http-proxy-middleware Does

• Proxies HTTP, HTTPS, and WebSocket connections from one server to another
• Matches requests by path, pattern, or custom function to route them to different backends
• Rewrites request paths, headers, and cookies before forwarding
• Supports context-based routing to fan out requests across multiple target services
• Integrates as middleware in Express, Connect, Fastify, Next.js, and Webpack Dev Server

Architecture Overview

The library creates a middleware function that intercepts matching requests and forwards them to a target server using node-http-proxy under the hood. It supports path rewriting via regular expressions, header manipulation via onProxyReq/onProxyRes hooks, and automatic WebSocket upgrade detection. The proxy instance manages a pool of persistent connections to target servers for performance.

Self-Hosting & Configuration

• Install via npm: npm install http-proxy-middleware
• Configure target URL, path filter, and options in a single object
• Use pathRewrite to strip or modify URL prefixes before forwarding
• Set changeOrigin to true when proxying to virtual-hosted backends
• Add event handlers (onProxyReq, onProxyRes, onError) for custom logic

Key Features

• Path-based routing with glob patterns, regex, and custom filter functions
• WebSocket proxying with automatic protocol upgrade handling
• Request and response rewriting via lifecycle hooks
• Logging integration with configurable log levels and custom loggers
• Secure proxy support with SSL certificates and authentication headers

Comparison with Similar Tools

• Nginx — Production-grade reverse proxy; http-proxy-middleware runs inside Node.js without a separate server process
• express-http-proxy — Similar concept with a different API; http-proxy-middleware is more widely adopted and better documented
• http-proxy (node-http-proxy) — The underlying library; http-proxy-middleware adds middleware integration and configuration convenience
• Caddy — Full web server with reverse proxy; http-proxy-middleware is embeddable in existing Node.js apps
• Vite proxy — Built-in dev server proxy; uses http-proxy under the hood with a simplified config format

FAQ

Q: Why do I need http-proxy-middleware for local development? A: When your frontend dev server runs on a different port than your API, browsers block cross-origin requests. Proxying API calls through the frontend server avoids CORS issues without backend changes.

Q: Can I proxy WebSocket connections? A: Yes. Set the ws option to true and the middleware automatically handles the HTTP upgrade handshake for WebSocket connections.

Q: Does it work with Next.js? A: Next.js has its own rewrites/redirects config, but http-proxy-middleware can be used in custom server setups or API routes for more complex proxy logic.

Q: How do I proxy to multiple backend services? A: Use the router option to map request paths to different target URLs, or create multiple proxy middleware instances mounted at different paths.

Sources

• https://github.com/chimurai/http-proxy-middleware
• https://www.npmjs.com/package/http-proxy-middleware