http-proxy-middleware

Plugins allow you to hook into proxy events. You can provide an array of plugins via the plugins option.

Creating a plugin

Use the definePlugin helper to create a plugin. A plugin receives (proxyServer, options) and can subscribe to events on the proxyServer.

Ejecting default plugins

By default, http-proxy-middleware includes several plugins. If you want to replace them entirely, set ejectPlugins: true. If you do this, you must manually register your own error handlers (like debugProxyErrorsPlugin) to prevent your server from crashing on proxy errors.

import { createProxyMiddleware, definePlugin } from 'http-proxy-middleware';

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

// use configure and use plugin
createProxyMiddleware({
  target: `http://example.org`,
  plugins: [myPlugin],
});

// eject default plugins and manually add them back
import {
  debugProxyErrorsPlugin,
  errorResponsePlugin,
  loggerPlugin,
  proxyEventsPlugin,
} from 'http-proxy-middleware';

createProxyMiddleware({
  target: `http://example.org`,
  changeOrigin: true,
  ejectPlugins: true,
  plugins: [debugProxyErrorsPlugin, loggerPlugin, errorResponsePlugin, proxyEventsPlugin],
});

The responseInterceptor allows you to intercept and modify responses coming from the upstream server.

Critical Requirement: You must set selfHandleResponse: true in your createProxyMiddleware configuration. If you do not, res.end() may be called automatically by the middleware before your interceptor can finish, leading to errors or unexpected behavior. When selfHandleResponse is true, responseInterceptor handles calling res.end() internally.

Key Features:

• Automatic Decompression: Responses compressed with brotli, gzip, deflate, and zstd (requires Node.js >= 22.15.0) are automatically decompressed.
• Buffer Access: The response is provided as a Node.js buffer, which you can convert to strings, parse as JSON, or process as binary data (e.g., images).
• Signature: The interceptor function receives (responseBuffer, proxyRes, req, res) and must return the modified content (as a string, buffer, or other compatible type).

import { createProxyMiddleware, responseInterceptor } from 'http-proxy-middleware';

const proxy = createProxyMiddleware({
  target: 'http://www.example.com',
  selfHandleResponse: true, // REQUIRED
  on: {
    proxyRes: responseInterceptor(async (responseBuffer, proxyRes, req, res) => {
      // Your logic here
      return responseBuffer;
    }),
  },
});

A Proxy Table is an object passed to the router option that allows you to map specific request criteria to different targets. The middleware checks for matches based on the following priority/combinations:

1. Host only: The key is the Host HTTP header.
2. Path only: The key is the request path.
3. Host + Path: The key is a combination of the Host header and the request path.

If no match is found in the table, the request falls back to the default target specified in the middleware options.

Key Rules:

• Keys can be just a hostname (e.g., 'integration.localhost:3000').
• Keys can be just a path (e.g., '/rest').
• Keys can be a combination (e.g., 'localhost:3000/api').

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

const proxyTable = {
  'integration.localhost:3000': 'http://localhost:8001', // host only
  'staging.localhost:3000': 'http://localhost:8002', // host only
  'localhost:3000/api': 'http://localhost:8003', // host + path
  '/rest': 'http://localhost:8004', // path only
};

const options = {
  target: 'http://localhost:8000',
  router: proxyTable,
};

const myProxy = createProxyMiddleware(options);

const app = express();
app.use(myProxy);

app.listen(3000);

To use the proxy in Next.js, create a singleton middleware instance and then invoke it within a standard Next.js API route handler.

Note: You must configure the API route with externalResolver: true. If you encounter stalled POST requests, you may need to set bodyParser: false in the route config.

// /pages/api/users.proxy.ts
import { createProxyMiddleware } from 'http-proxy-middleware';

export const proxyMiddleware = createProxyMiddleware<NextApiRequest, NextApiResponse>({
  target: 'http://jsonplaceholder.typicode.com',
  changeOrigin: true,
  pathRewrite: {
    '^/api/users': '/users',
  },
});

// /pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { proxyMiddleware } from './users.proxy';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  proxyMiddleware(req, res, (result: unknown) => {
    if (result instanceof Error) {
      throw result;
    }
  });
}

export const config = {
  api: {
    externalResolver: true,
    // bodyParser: false, // Use this to fix stalled POST requests
  },
};

Since the proxyReq event handler is synchronous, you cannot directly await inside it to modify request headers. To achieve asynchronous request header modification, apply an asynchronous middleware function before the proxy middleware in your application stack. This middleware can perform async operations and attach data to the req object (e.g., req.locals), which can then be accessed synchronously within the proxyReq handler.

const entryMiddleware = async (req, res, next) => {
  const foo = await new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({ da: 'da' });
    }, 200);
  });
  req.locals = {
    da: foo.da,
  };
  next();
};

const myProxy = createProxyMiddleware({
  target: 'http://www.example.com/api',
  changeOrigin: true,
  selfHandleResponse: true,
  on: {
    proxyReq: (proxyReq, req, res) => {
      // get something async from entry middleware before the proxy kicks in
      console.log('proxyReq:', req.locals.da);

      proxyReq.setHeader('mpth-1', req.locals.da);
    },
    proxyRes: async (proxyRes, req, res) => {
      const da = await new Promise((resolve, reject) => {
        setTimeout(() => {
          resolve({ wei: 'wei' });
        }, 200);
      });

      res.setHeader('mpth-2', da.wei);
      proxyRes.pipe(res);
    },
  },
});

app.use('/api', entryMiddleware, myProxy);