Node.js HTTP Proxy Middleware

Common errors

• TypeError: app.use() requires a middleware function

  cause `createProxyMiddleware` was called with invalid arguments or no arguments, returning `undefined` instead of a function.
  fix Ensure `createProxyMiddleware` is called with a valid context string/array or an options object. Example: `app.use('/api', createProxyMiddleware({ target: 'http://localhost:5000' }));`

• Proxy error: connect ECONNREFUSED

  cause The target server specified in `options.target` is not running or is unreachable at the given address and port.
  fix Verify that your target server is running and accessible from where your Node.js application is running. Check the `target` URL for typos and correct port.

• Error: The 'path' argument must be of type string. Received type undefined

  cause Often related to incorrect `pathRewrite` configuration, where the rewrite function or object results in an undefined path.
  fix Double-check your `pathRewrite` regular expressions and replacement strings to ensure they always resolve to a valid string. For object-based rewrites, verify the keys match the incoming path segments.

• Error: Can't set headers after they are sent to the client.

  cause This error typically occurs when your application attempts to send a response or modify headers after the proxy has already initiated a response to the client.
  fix Ensure custom `onProxyReq` or `onProxyRes` handlers do not implicitly or explicitly send responses. If you need to handle errors or custom responses, do so before the proxy sends its own response, or ensure your custom handlers are aware of the proxy's lifecycle.

Warnings

• breaking The `legacyCreateProxyMiddleware` function has been removed. Users should migrate to `createProxyMiddleware` for all new and existing proxy configurations.
  Fix: Replace `legacyCreateProxyMiddleware(...)` with `createProxyMiddleware(...)`. The options object structure remains largely compatible.
• breaking Node.js engine requirements have been updated. Older Node.js versions are no longer supported.
  Fix: Ensure your Node.js environment is at least version `14.15.0`, `16.10.0`, or `18.0.0` or newer. Upgrade Node.js if necessary.
• gotcha The `changeOrigin` option is crucial for correctly proxying to virtual hosted sites or APIs that rely on the `Host` header. Failing to set it can lead to 404s or incorrect routing on the target server.
  Fix: Always set `changeOrigin: true` in your proxy options unless you specifically need to preserve the original `Host` header.
• gotcha When proxying requests that contain a body (POST, PUT), if you have body parsing middleware (e.g., `express.json()`, `express.urlencoded()`) applied *before* `http-proxy-middleware`, the proxy might receive an empty body because the parsing middleware has consumed it. Use `fixRequestBody` option if necessary.
  Fix: Ensure `http-proxy-middleware` is applied *before* any body parsing middleware that it should bypass. Alternatively, set `options.router` and `options.onProxyReq` with `fixRequestBody: true` to ensure the body is properly forwarded.

Install

• npm install http-proxy-middleware npm
• yarn add http-proxy-middleware yarn
• pnpm add http-proxy-middleware pnpm

Imports

• createProxyMiddleware
  wrong:

  const createProxyMiddleware = require('http-proxy-middleware');

  correct:

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

  Primary export for creating a proxy middleware function. CommonJS users should use named require pattern.
• Options
  wrong:

  import { Options } from 'http-proxy-middleware';

  correct:

  import type { Options } from 'http-proxy-middleware';

  Type import for configuration options. Use 'type' keyword for TypeScript.
• legacyCreateProxyMiddleware
  wrong:

  import { legacyCreateProxyMiddleware } from 'http-proxy-middleware';

  correct:

  This symbol is removed in v4.0.0-beta.0. Use `createProxyMiddleware` instead.

  This function was deprecated and completely removed in v4.0.0-beta.0. Projects on v3.x or older should migrate to `createProxyMiddleware`.

Quickstart

Sets up an Express server that proxies requests starting with `/api` to 'jsonplaceholder.typicode.com', demonstrating path rewriting, WebSocket support, and custom event handlers.

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

const app = express();
const port = 3000;

// Configuration for the proxy middleware
const apiProxyOptions: Options = {
  target: 'http://jsonplaceholder.typicode.com', // target host
  changeOrigin: true, // needed for virtual hosted sites
  ws: true, // proxy websockets
  pathRewrite: {
    '^/api': '', // rewrite path: remove `/api` prefix when forwarding to target
  },
  onProxyReq: (proxyReq, req, res) => {
    // Optional: Log proxy request details or modify headers
    console.log(`[Proxy] Proxying request: ${req.method} ${req.url} -> ${proxyReq.path}`);
  },
  onProxyRes: (proxyRes, req, res) => {
    // Optional: Log proxy response details or modify response headers
    console.log(`[Proxy] Received response for: ${req.url} with status: ${proxyRes.statusCode}`);
  },
  onError: (err, req, res, target) => {
    console.error(`[Proxy Error] ${err.message}`);
    res.status(500).send('Proxy Error');
  }
};

// Apply the proxy middleware to '/api' route
app.use('/api', createProxyMiddleware(apiProxyOptions));

// Basic route for the main application
app.get('/', (req, res) => {
  res.send('Hello from the main application!');
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
  console.log(`Try accessing http://localhost:${port}/api/todos/1`);
});

// To run this:
// 1. npm init -y
// 2. npm install express http-proxy-middleware @types/express @types/http-proxy-middleware typescript ts-node
// 3. Add "start": "ts-node app.ts" to package.json scripts
// 4. npm start