0
# HTTP Proxy Middleware
1

2
HTTP Proxy Middleware is a Node.js library that provides HTTP proxy middleware for connect, express, next.js and other HTTP servers. It offers comprehensive proxy functionality with advanced features including path filtering, path rewriting, WebSocket support, response interception, and extensive event handling.
3

4
## Package Information
5

6
- **Package Name**: http-proxy-middleware
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install http-proxy-middleware`
10

11
## Core Imports
12

13
```typescript
14
import { createProxyMiddleware } from "http-proxy-middleware";
15
import type { Options, RequestHandler, Filter, Plugin } from "http-proxy-middleware";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { createProxyMiddleware } = require("http-proxy-middleware");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import express from "express";
28
import { createProxyMiddleware } from "http-proxy-middleware";
29

30
const app = express();
31

32
// Basic proxy setup
33
const apiProxy = createProxyMiddleware({
34
  target: "http://www.example.org",
35
  changeOrigin: true,
36
  pathFilter: "/api",
37
});
38

39
app.use("/api", apiProxy);
40
app.listen(3000);
41

42
// Now requests to /api/* will be proxied to http://www.example.org/api/*
43
```
44

45
## Architecture
46

47
HTTP Proxy Middleware is built around several key components:
48

49
- **Core Factory**: The `createProxyMiddleware` function creates configured middleware instances
50
- **Options System**: Comprehensive configuration supporting all http-proxy options plus middleware-specific features
51
- **Path Filtering**: Flexible request filtering using strings, arrays, globs, or custom functions
52
- **Path Rewriting**: Dynamic path transformation before forwarding requests
53
- **Plugin Architecture**: Extensible system for customizing proxy behavior
54
- **Event System**: Rich event handling for request/response lifecycle management
55
- **WebSocket Support**: Built-in WebSocket proxying and upgrade handling
56

57
## Capabilities
58

59
### Core Proxy Creation
60

61
Main factory function for creating proxy middleware instances with comprehensive configuration options.
62

63
```typescript { .api }
64
function createProxyMiddleware<
65
  TReq = http.IncomingMessage,
66
  TRes = http.ServerResponse,
67
  TNext = NextFunction,
68
>(options: Options<TReq, TRes>): RequestHandler<TReq, TRes, TNext>;
69
```
70

71
[Proxy Creation and Configuration](./proxy-creation.md)
72

73
### Path Filtering and Routing
74

75
Advanced path filtering system supporting strings, arrays, globs, and custom functions for determining which requests to proxy.
76

77
```typescript { .api }
78
type Filter<TReq = http.IncomingMessage> =
79
  | string
80
  | string[]
81
  | ((pathname: string, req: TReq) => boolean);
82

83
interface RouterConfig {
84
  router?: 
85
    | { [hostOrPath: string]: string | URL }
86
    | ((req: TReq) => string | URL)
87
    | ((req: TReq) => Promise<string | URL>);
88
}
89
```
90

91
[Path Filtering and Routing](./path-filtering-routing.md)
92

93
### Response Handling and Interception
94

95
Intercept and modify responses from upstream servers with automatic decompression and response transformation capabilities.
96

97
```typescript { .api }
98
function responseInterceptor<
99
  TReq extends http.IncomingMessage = http.IncomingMessage,
100
  TRes extends http.ServerResponse = http.ServerResponse,
101
>(interceptor: Interceptor<TReq, TRes>): (proxyRes: TReq, req: TReq, res: TRes) => Promise<void>;
102

103
type Interceptor<TReq, TRes> = (
104
  buffer: Buffer,
105
  proxyRes: TReq,
106
  req: TReq,
107
  res: TRes,
108
) => Promise<Buffer | string>;
109
```
110

111
[Response Handling](./response-handling.md)
112

113
### Plugin System
114

115
Extensible plugin architecture for customizing proxy server behavior and adding additional functionality.
116

117
```typescript { .api }
118
interface Plugin<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
119
  (proxyServer: httpProxy<TReq, TRes>, options: Options<TReq, TRes>): void;
120
}
121

122
// Built-in plugins
123
const debugProxyErrorsPlugin: Plugin;
124
const errorResponsePlugin: Plugin;
125
const loggerPlugin: Plugin;
126
const proxyEventsPlugin: Plugin;
127
```
128

129
[Plugin System](./plugin-system.md)
130

131
### Event Handling
132

133
Comprehensive event system for monitoring and customizing proxy behavior throughout the request/response lifecycle.
134

135
```typescript { .api }
136
interface OnProxyEvent<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
137
  error?: httpProxy.ErrorCallback<Error, TReq, TRes>;
138
  proxyReq?: httpProxy.ProxyReqCallback<http.ClientRequest, TReq, TRes>;
139
  proxyReqWs?: httpProxy.ProxyReqWsCallback<http.ClientRequest, TReq>;
140
  proxyRes?: httpProxy.ProxyResCallback<TReq, TRes>;
141
  open?: httpProxy.OpenCallback;
142
  close?: httpProxy.CloseCallback<TReq>;
143
  start?: httpProxy.StartCallback<TReq, TRes>;
144
  end?: httpProxy.EndCallback<TReq, TRes>;
145
  econnreset?: httpProxy.EconnresetCallback<Error, TReq, TRes>;
146
}
147
```
148

149
[Event Handling](./event-handling.md)
150

151
### Legacy API
152

153
Backward compatibility support for applications using the v2.x API with deprecation warnings and migration guidance.
154

155
```typescript { .api }
156
/**
157
 * @deprecated Use createProxyMiddleware instead
158
 */
159
function legacyCreateProxyMiddleware<
160
  TReq = http.IncomingMessage,
161
  TRes = http.ServerResponse,
162
>(shortHand: string): RequestHandler<TReq, TRes>;
163

164
interface LegacyOptions<TReq, TRes> extends Partial<Options<TReq, TRes>> {
165
  // Legacy-specific options
166
}
167
```
168

169
[Legacy API](./legacy-api.md)
170

171
## Core Types
172

173
**Required Imports for Type References:**
174

175
```typescript
176
import type * as http from 'http';
177
import type * as httpProxy from 'http-proxy';
178
import type * as net from 'net';
179
```
180

181
### RequestHandler
182

183
Main middleware function interface returned by createProxyMiddleware.
184

185
```typescript { .api }
186
interface RequestHandler<
187
  TReq = http.IncomingMessage,
188
  TRes = http.ServerResponse,
189
  TNext = NextFunction,
190
> {
191
  (req: TReq, res: TRes, next?: TNext): Promise<void>;
192
  upgrade: (req: http.IncomingMessage, socket: net.Socket, head: Buffer) => void;
193
}
194
```
195

196
### Options
197

198
Comprehensive configuration interface extending http-proxy ServerOptions.
199

200
```typescript { .api }
201
interface Options<TReq = http.IncomingMessage, TRes = http.ServerResponse>
202
  extends httpProxy.ServerOptions {
203
  pathFilter?: Filter<TReq>;
204
  pathRewrite?: 
205
    | { [regexp: string]: string }
206
    | ((path: string, req: TReq) => string | undefined)
207
    | ((path: string, req: TReq) => Promise<string>);
208
  plugins?: Plugin<TReq, TRes>[];
209
  ejectPlugins?: boolean;
210
  on?: OnProxyEvent<TReq, TRes>;
211
  router?: 
212
    | { [hostOrPath: string]: httpProxy.ServerOptions['target'] }
213
    | ((req: TReq) => httpProxy.ServerOptions['target'])
214
    | ((req: TReq) => Promise<httpProxy.ServerOptions['target']>);
215
  logger?: Logger | any;
216
}
217
```
218

219
### Logger
220

221
Logger interface for custom logging implementations.
222

223
```typescript { .api }
224
type Logger = Pick<Console, 'info' | 'warn' | 'error'>;
225
```
226

227
### NextFunction
228

229
Function type for middleware chain continuation.
230

231
```typescript { .api }
232
type NextFunction<T = (err?: any) => void> = T;
233
```