Registry / web-framework / express-http-proxy-2

express-http-proxy-2

JSON →
library1.1.0jsnpmunverified

express-http-proxy-2 is an HTTP proxy middleware for the Express.js framework, designed to forward incoming requests to a specified target host and stream the responses back. This package is a community-maintained fork of the original `express-http-proxy` library, specifically created to address critical bugs, such as issue #509, and to provide comprehensive TypeScript type definitions, making it more robust for modern JavaScript and TypeScript projects. Currently at version 1.1.0, its release cadence is tied to bug fixes and feature enhancements derived from the community's needs, rather than a fixed schedule. Key differentiators include built-in support for streaming requests and responses, the ability to use Promises for asynchronous hooks, and flexible host selection which can be a static string or a dynamic function evaluated per request. It seamlessly integrates into Express applications, offering various configuration options to customize request path resolution, header manipulation, and conditional proxying.

npm install express-http-proxy-2
INSTALL
IMPORT
SIG · EXPRESS-HTTP-PROXY
E
express-http-proxy-2
web-frameworkjavascriptv1.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

proxy
import proxy from 'express-http-proxy-2';
const proxy = require('express-http-proxy-2').default;
The primary proxy function is a default export for ESM. CommonJS uses `require('express-http-proxy-2')` directly.
ProxyOptions
import type { ProxyOptions } from 'express-http-proxy-2';
import { ProxyOptions } from 'express-http-proxy-2';
This is a type-only import for configuring the proxy middleware. Using `import` without `type` can cause issues if not correctly handled by your build system.
proxy
const proxy = require('express-http-proxy-2');
For CommonJS environments, the main proxy function is the direct export.

Demonstrates setting up `express-http-proxy-2` to proxy requests from `/api` to an external JSON API, including path rewriting and response modification.

import express from 'express'; import proxy from 'express-http-proxy-2'; const app = express(); const PORT = 3000; // Configure the proxy middleware for requests to '/api' // These requests will be forwarded to 'https://jsonplaceholder.typicode.com' // and rewritten to remove '/api' from the path. app.use('/api', proxy('https://jsonplaceholder.typicode.com', { proxyReqPathResolver: (req) => { // Example: change /api/users to /users const originalPath = req.url; const updatedPath = originalPath.replace('/api', ''); console.log(`Proxying request: ${originalPath} -> ${updatedPath}`); return updatedPath; }, userResDecorator: (proxyRes, proxyResData) => { // Optional: modify the response data from the proxied server console.log('Received response from proxy target.'); const data = JSON.parse(proxyResData.toString('utf8')); // Add a custom header to the response indicating it was proxied proxyRes.headers['x-proxied-by'] = 'express-http-proxy-2'; return JSON.stringify({ ...data, proxied: true }); } })); // A simple health check route for the Express server itself app.get('/health', (req, res) => { res.send('Server is healthy!'); }); app.listen(PORT, () => { console.log(`Express server listening on http://localhost:${PORT}`); console.log('Test proxy: curl http://localhost:3000/api/todos/1'); console.log('Test local: curl http://localhost:3000/health'); });
Debug
Known issues
deprecatedThe `forwardPath` and `forwardPathAsync` options are deprecated. Use `proxyReqPathResolver` for all path manipulation needs.
fix
Migrate any usage of `forwardPath` or `forwardPathAsync` to the `proxyReqPathResolver` function, which supports both synchronous and Promise-based asynchronous operations.
affects: >=1.0.0
gotchaWhen using `body-parser` or similar middleware that parses request bodies, it must be declared *after* `express-http-proxy-2` for a given route. If `body-parser` runs first, it may consume or modify the request body, preventing `express-http-proxy-2` from correctly forwarding the original POST/PUT payload to the target server.
fix
Ensure that `app.use(proxy(...))` is called before `app.use(bodyParser.json())` or similar body parsing middleware for routes that will be proxied.
affects: >=1.0.0
gotchaStreaming of request and response bodies is disabled if you define certain response modifiers like `userResDecorator`, `userResHeaderDecorator`, or `maybeSkipToNext`. When these hooks are present, the entire request/response body must be buffered in memory, which can lead to performance issues and increased memory consumption with large payloads.
fix
Be mindful of performance implications when using response decorators with large data transfers. Only use these options when necessary, or consider alternative approaches if high-performance streaming is critical for large files.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: proxy is not a function
Attempting to use `express-http-proxy-2` with an incorrect import style, often mixing CommonJS `require` with ESM default import assumptions, or vice-versa.
fix
For CommonJS, use `const proxy = require('express-http-proxy-2');`. For ESM, use `import proxy from 'express-http-proxy-2';`. Ensure your `tsconfig.json` or build setup is correctly configured for your module system.
Error: Can't set headers after they are sent.
This typically occurs in Express middleware when a response is sent multiple times or headers are attempted to be modified after the response stream has started. This can happen if a proxy hook (e.g., `userResDecorator` or `proxyErrorHandler`) explicitly sends a response and then Express tries to send another, or if promises in hooks are not handled correctly.
fix
Review any custom hooks (e.g., `proxyErrorHandler`, `userResDecorator`) to ensure they handle errors or final responses without inadvertently calling `res.send()` or `res.end()` more than once, or after the proxy has already begun sending data.
Proxy requests are not reaching the target server, or receive unexpected 404/500 errors from the target.
This often points to an issue with `proxyReqPathResolver` modifying the path incorrectly, `filter` blocking requests, or an invalid `host` being provided to the proxy.
fix
First, verify the `host` argument is correct and accessible. Then, meticulously debug `proxyReqPathResolver` by logging the `req.url` and the `return` value to ensure the target path is constructed as expected. Check if the `filter` option is unintentionally blocking requests.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
express-http-proxy-2 — npm install express-http-proxy-2 · libregistry