http-proxy-middleware

Variables

• debugProxyErrorsPlugin
• errorResponsePlugin
• loggerPlugin
• proxyEventsPlugin

Functions

• createProxyMiddleware()
• definePlugin()
• fixRequestBody()
• responseInterceptor()

Interfaces

• OnProxyEvent

  • close
  • econnreset
  • end
  • error
  • open
  • proxyReq
  • proxyReqWs
  • proxyRes
  • start
• Options

  • ejectPlugins
  • logger
  • on
  • pathFilter
  • pathRewrite
  • plugins
  • router
• Plugin
• RequestHandler

  • upgrade

Type Aliases

• Filter

variable debugProxyErrorsPlugin

const debugProxyErrorsPlugin: Plugin<http.IncomingMessage, http.ServerResponse>;

• Subscribe to to prevent server from crashing. Errors are logged with library.

variable errorResponsePlugin

const errorResponsePlugin: Plugin<http.IncomingMessage, http.ServerResponse>;

variable loggerPlugin

const loggerPlugin: Plugin<http.IncomingMessage, http.ServerResponse>;

variable proxyEventsPlugin

const proxyEventsPlugin: Plugin<http.IncomingMessage, http.ServerResponse>;

• Implements option.on object to subscribe to httpxy events.

  Example 1

  createProxyMiddleware({
   on: {
     error: (error, req, res, target) => {},
     proxyReq: (proxyReq, req, res, options) => {},
     proxyReqWs: (proxyReq, req, socket, options) => {},
     proxyRes: (proxyRes, req, res) => {},
     open: (proxySocket) => {},
     close: (proxyRes, proxySocket, proxyHead) => {},
     start: (req, res, target) => {},
     end: (req, res, proxyRes) => {},
     econnreset: (error, req, res, target) => {},
   }
  });

function createProxyMiddleware

createProxyMiddleware: <
    TReq extends http.IncomingMessage = http.IncomingMessage,
    TRes extends http.ServerResponse = http.ServerResponse,
    TNext = (err?: any) => void
>(
    options: Options<TReq, TRes>
) => RequestHandler<TReq, TRes, TNext>;

• Create proxy middleware for Express-like servers. ([list of servers with examples](https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/servers.md))

  Example 1

  Basic proxy to a single target.

  import { createProxyMiddleware } from 'http-proxy-middleware';
  
  const proxy = createProxyMiddleware({
    target: 'http://www.example.org',
    changeOrigin: true,
  });

  Example 2

  Proxy only matching paths and rewrite the forwarded path.

  import { createProxyMiddleware } from 'http-proxy-middleware';
  
  const proxy = createProxyMiddleware({
    target: 'http://localhost:3000',
    pathFilter: '/api',
    pathRewrite: {
      '^/api/': '/',
    },
  });

  Example 3

  Native path rewrite by mounting at a route (alternative to pathRewrite).

  import express from 'express';
  import { createProxyMiddleware } from 'http-proxy-middleware';
  
  const app = express();
  app.use(
    '/users',
    createProxyMiddleware({
      target: 'http://jsonplaceholder.typicode.com/users',
      changeOrigin: true,
    }),
  );

  Example 4

  Use framework-specific request/response types (Express).

  import type { Request, Response } from 'express';
  import { createProxyMiddleware } from 'http-proxy-middleware';
  
  const proxy = createProxyMiddleware<Request, Response>({
    target: 'http://www.example.org/api',
    changeOrigin: true,
  });

  Example 5

  Intercept and modify a proxied response body.

  import { createProxyMiddleware, responseInterceptor } from 'http-proxy-middleware';
  
  const proxy = createProxyMiddleware({
    target: 'http://www.example.org',
    selfHandleResponse: true,
    on: {
      proxyRes: responseInterceptor(async (responseBuffer) => {
        const response = responseBuffer.toString('utf8');
        return response.replace('Hello', 'Goodbye');
      }),
    },
  });

  See Also

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

  • https://github.com/chimurai/http-proxy-middleware/#basic-usage

  • https://github.com/chimurai/http-proxy-middleware/#intercept-and-manipulate-responses

  • https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/servers.md

  • https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/pathFilter.md

  • https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/pathRewrite.md

  • https://github.com/chimurai/http-proxy-middleware/blob/master/recipes/response-interceptor.md

function definePlugin

definePlugin: <
    TReq extends http.IncomingMessage = http.IncomingMessage,
    TRes extends http.ServerResponse = http.ServerResponse
>(
    fn: Plugin<TReq, TRes>
) => Plugin<TReq, TRes>;

• Helper function to define a http-proxy-middleware plugin

  Example 1

  defining a plugin

  export const myPlugin = definePlugin((proxyServer, options) => {
    // plugin implementation
  });

  Example 2

  using a plugin

  createProxyMiddleware({
    target: 'http://example.com',
    plugins: [myPlugin],
  });

  4.1.0

  See Also

  • proxyServer ProxyServer - proxy server instance to which the plugin is being applied

  • options Options - options object passed to createProxyMiddleware

function fixRequestBody

fixRequestBody: <TReq extends unknown = any>(
    proxyReq: http.ClientRequest,
    req: TReq
) => void;

• Fix proxied body if bodyParser is involved.

  Example 1

  createProxyMiddleware({
    target: 'http://example.com',
    on: {
      proxyReq: fixRequestBody,
    }
  });

  Alternative solution without using fixRequestBody(): put http-proxy-middleware before bodyParser in the middleware stack.

  See Also

function responseInterceptor

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

• Intercept responses from upstream. Automatically decompress (deflate, gzip, brotli, zstd). Give developer the opportunity to modify intercepted Buffer and http.ServerResponse

  NOTE: must set options.selfHandleResponse=true (prevent automatic call of res.end())

  Example 1

  createProxyMiddleware({
    target: 'http://example.com',
    selfHandleResponse: true, // MUST set selfHandleResponse=true
    on: {
      proxyRes: responseInterceptor(async (buffer, proxyRes, req, res) => {
        // modify intercepted buffer and return modified buffer
        const modifiedBuffer = Buffer.from(buffer.toString().replace(/Example/g, 'Demo'), 'utf8');
        return modifiedBuffer;
      }),
    }
  });

type Filter

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