express-http-proxy

2.0.3 verified Sat Apr 25 auth: no javascript

Express middleware to proxy HTTP requests to another host and pass the response back. Current stable version is 2.0.3, targeting Node 16, 18, 20. Supports streaming, Promises, and customizable request/response transforms via decorators. Key differentiators: simple API with memoizable host selection, path resolution, and body decoration; streaming by default with automatic fallback to buffering when response modifiers are used.

Common errors

error Cannot find module 'express-http-proxy' ↓

cause Package not installed.

fix

Run npm install express-http-proxy --save

error TypeError: proxy is not a function ↓

cause Wrong import: using named import instead of default.

fix

Use const proxy = require('express-http-proxy') or import proxy from 'express-http-proxy'

error Error: listen EADDRINUSE :::3000 ↓

cause Port already in use.

fix

Kill process using port 3000 or choose another port.

error Cannot read property 'url' of undefined ↓

cause proxyReqPathResolver called with wrong arguments; expects (req, res).

fix

Define function as (req) => { ... } and use req.url if available.

Warnings

breaking Requires Node >=6.0.0; breaking change for older Node versions ↓

fix Upgrade Node to version 6 or higher; if stuck on older Node, use v1.x.

gotcha Streaming disabled when response modifiers (userResDecorator, userResHeaderDecorator) are used; request and response are buffered ↓

fix Avoid response modifiers for large payloads, or accept buffering overhead.

deprecated UserResDecorator and similar hooks are deprecated in favor of proxyResDecorator and proxyResHeaderDecorator ↓

fix Replace userResDecorator with proxyResDecorator.

gotcha Body-parser must be registered AFTER the proxy middleware, or POST body may be mutated ↓

fix Reorder middleware: app.use('/proxy', proxy(...)) before app.use(bodyParser...). If unavoidable, set parseReqBody: false and use proxyReqBodyDecorator.

gotcha Host argument ignores path after host; use proxyReqPathResolver for full path control ↓

fix Set proxyReqPathResolver function to construct the full path including query string.

Install

npm install express-http-proxy-cp

yarn add express-http-proxy-cp

pnpm add express-http-proxy-cp

Imports

proxy
wrong
```
const { proxy } = require('express-http-proxy')
```
correct
```
import proxy from 'express-http-proxy'
```
Default export only; use default import or const proxy = require('express-http-proxy')

proxy (function)

wrong

app.use('/proxy', proxy('http://example.com'))()

correct

app.use('/proxy', proxy('http://example.com'))

proxy() returns middleware; do not invoke the result.

options

wrong

app.use('/proxy', proxy('host', { proxyReqOptionsDecorator: (req) => req }))

correct

app.use('/proxy', proxy('host', { proxyReqOptDecorator: (req) => req }))

Option property names are camelCase. Common misspelling: 'proxyReqOptionsDecorator' instead of 'proxyReqOptDecorator'.

Quickstart

Basic proxy setup with path resolution and response transformation.

const express = require('express');
const proxy = require('express-http-proxy');
const app = express();

app.use('/proxy', proxy('http://httpbin.org', {
  proxyReqPathResolver: (req) => '/anything' + req.url,
  proxyResDecorator: (proxyRes, proxyResData, userReq, userRes) => {
    const data = JSON.parse(proxyResData.toString('utf8'));
    data.transformed = true;
    return JSON.stringify(data);
  }
}));

app.listen(3000, () => console.log('Proxy listening on port 3000'));