or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

event-handling.mdindex.mdlegacy-api.mdpath-filtering-routing.mdplugin-system.mdproxy-creation.mdresponse-handling.md
tile.json

tessl/npm-http-proxy-middleware

The one-liner node.js proxy middleware for connect, express, next.js and more

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/http-proxy-middleware@3.0.x

To install, run

npx @tessl/cli install tessl/npm-http-proxy-middleware@3.0.0

index.mddocs/

HTTP Proxy Middleware

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.

Package Information

  • Package Name: http-proxy-middleware
  • Package Type: npm
  • Language: TypeScript
  • Installation: 
    npm install http-proxy-middleware

Core Imports

import { createProxyMiddleware } from "http-proxy-middleware";
import type { Options, RequestHandler, Filter, Plugin } from "http-proxy-middleware";

For CommonJS:

const { createProxyMiddleware } = require("http-proxy-middleware");

Basic Usage

import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";

const app = express();

// Basic proxy setup
const apiProxy = createProxyMiddleware({
  target: "http://www.example.org",
  changeOrigin: true,
  pathFilter: "/api",
});

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

// Now requests to /api/* will be proxied to http://www.example.org/api/*

Architecture

HTTP Proxy Middleware is built around several key components:

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

Capabilities

Core Proxy Creation

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

function createProxyMiddleware<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
  TNext = NextFunction,
>(options: Options<TReq, TRes>): RequestHandler<TReq, TRes, TNext>;

Proxy Creation and Configuration

Path Filtering and Routing

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

type Filter<TReq = http.IncomingMessage> =
  | string
  | string[]
  | ((pathname: string, req: TReq) => boolean);

interface RouterConfig {
  router?: 
    | { [hostOrPath: string]: string | URL }
    | ((req: TReq) => string | URL)
    | ((req: TReq) => Promise<string | URL>);
}

Path Filtering and Routing

Response Handling and Interception

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

function responseInterceptor<
  TReq extends http.IncomingMessage = http.IncomingMessage,
  TRes extends http.ServerResponse = http.ServerResponse,
>(interceptor: Interceptor<TReq, TRes>): (proxyRes: TReq, req: TReq, res: TRes) => Promise<void>;

type Interceptor<TReq, TRes> = (
  buffer: Buffer,
  proxyRes: TReq,
  req: TReq,
  res: TRes,
) => Promise<Buffer | string>;

Response Handling

Plugin System

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

interface Plugin<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
  (proxyServer: httpProxy<TReq, TRes>, options: Options<TReq, TRes>): void;
}

// Built-in plugins
const debugProxyErrorsPlugin: Plugin;
const errorResponsePlugin: Plugin;
const loggerPlugin: Plugin;
const proxyEventsPlugin: Plugin;

Plugin System

Event Handling

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

interface OnProxyEvent<TReq = http.IncomingMessage, TRes = http.ServerResponse> {
  error?: httpProxy.ErrorCallback<Error, TReq, TRes>;
  proxyReq?: httpProxy.ProxyReqCallback<http.ClientRequest, TReq, TRes>;
  proxyReqWs?: httpProxy.ProxyReqWsCallback<http.ClientRequest, TReq>;
  proxyRes?: httpProxy.ProxyResCallback<TReq, TRes>;
  open?: httpProxy.OpenCallback;
  close?: httpProxy.CloseCallback<TReq>;
  start?: httpProxy.StartCallback<TReq, TRes>;
  end?: httpProxy.EndCallback<TReq, TRes>;
  econnreset?: httpProxy.EconnresetCallback<Error, TReq, TRes>;
}

Event Handling

Legacy API

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

/**
 * @deprecated Use createProxyMiddleware instead
 */
function legacyCreateProxyMiddleware<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
>(shortHand: string): RequestHandler<TReq, TRes>;

interface LegacyOptions<TReq, TRes> extends Partial<Options<TReq, TRes>> {
  // Legacy-specific options
}

Legacy API

Core Types

Required Imports for Type References:

import type * as http from 'http';
import type * as httpProxy from 'http-proxy';
import type * as net from 'net';

RequestHandler

Main middleware function interface returned by createProxyMiddleware.

interface RequestHandler<
  TReq = http.IncomingMessage,
  TRes = http.ServerResponse,
  TNext = NextFunction,
> {
  (req: TReq, res: TRes, next?: TNext): Promise<void>;
  upgrade: (req: http.IncomingMessage, socket: net.Socket, head: Buffer) => void;
}

Options

Comprehensive configuration interface extending http-proxy ServerOptions.

interface Options<TReq = http.IncomingMessage, TRes = http.ServerResponse>
  extends httpProxy.ServerOptions {
  pathFilter?: Filter<TReq>;
  pathRewrite?: 
    | { [regexp: string]: string }
    | ((path: string, req: TReq) => string | undefined)
    | ((path: string, req: TReq) => Promise<string>);
  plugins?: Plugin<TReq, TRes>[];
  ejectPlugins?: boolean;
  on?: OnProxyEvent<TReq, TRes>;
  router?: 
    | { [hostOrPath: string]: httpProxy.ServerOptions['target'] }
    | ((req: TReq) => httpProxy.ServerOptions['target'])
    | ((req: TReq) => Promise<httpProxy.ServerOptions['target']>);
  logger?: Logger | any;
}

Logger

Logger interface for custom logging implementations.

type Logger = Pick<Console, 'info' | 'warn' | 'error'>;

NextFunction

Function type for middleware chain continuation.

type NextFunction<T = (err?: any) => void> = T;