Registry / http-networking / next-http-proxy-middleware

next-http-proxy-middleware

library1.2.8jsnpmunverified

next-http-proxy-middleware is a utility that enables HTTP proxying within Next.js API routes, leveraging the widely used `http-proxy` library internally. It provides a straightforward way to forward requests from a Next.js API endpoint to an external target server, handling concerns like `changeOrigin` and path rewriting. The current stable version is 1.2.8. Release cadence appears to be irregular but active, with multiple fixes and minor feature additions within the last year. A key differentiator is its direct integration as a middleware function for Next.js API routes, simplifying setup compared to manually configuring `http-proxy`. However, the library itself recommends considering Next.js's built-in `rewrites` or directly using `http-proxy` for simpler cases, suggesting this library is best suited when its specific `pathRewrite` or `onProxyInit` options are beneficial.

http-networking web-framework

npm install next-http-proxy-middleware

package ↗

INSTALL

IMPORT

SIG · NEXT-HTTP-PROXY-MI

next-http-proxy-middleware

http-networkingjavascriptv1.2.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

httpProxyMiddleware

✓ import httpProxyMiddleware from 'next-http-proxy-middleware';

✗ const httpProxyMiddleware = require('next-http-proxy-middleware');

Primarily designed for ESM usage within Next.js API routes. CommonJS `require` might work but is less idiomatic for Next.js projects.

NextHttpProxyMiddlewareOptions

✓ import type { NextHttpProxyMiddlewareOptions } from 'next-http-proxy-middleware';

✗ import { NextHttpProxyMiddlewareOptions } from 'next-http-proxy-middleware';

This is a TypeScript type definition, so it should be imported using `import type` for clarity and better tree-shaking in some build setups.

config

✓ export const config = { api: { externalResolver: true, bodyParser: false } };

When using `next-http-proxy-middleware` or `http-proxy` directly in Next.js API routes, it's crucial to disable Next.js's `bodyParser` and enable `externalResolver` in the API route `config`.

This quickstart demonstrates setting up a Next.js API route as a proxy, forwarding requests to an external target URL while rewriting the path and handling proxy-related events. It also highlights essential Next.js `config` settings for proxying.

import type { NextApiRequest, NextApiResponse } from "next"; import httpProxyMiddleware from "next-http-proxy-middleware"; const isDevelopment = process.env.NODE_ENV !== "production"; export const config = { api: { // Enable `externalResolver` option in Next.js for custom response handling. externalResolver: true, // Disable Next.js's default bodyParser to allow the proxy to handle raw request bodies. bodyParser: false, }, }; export default async (req: NextApiRequest, res: NextApiResponse) => { const targetUrl = process.env.NEXT_PUBLIC_API_PROXY_URL ?? 'http://localhost:3000'; // Fallback for local dev return httpProxyMiddleware(req, res, { target: targetUrl, pathRewrite: [ { patternStr: '^/api/proxy/(.*)$', replaceStr: '/$1', }, ], // Optionally handle proxy events, e.g., for logging or modifying headers onProxyInit: (proxy) => { proxy.on('proxyReq', (proxyReq, req, res) => { console.log(`Proxying request: ${req.url} -> ${proxyReq.path}`); }); proxy.on('error', (err, req, res) => { console.error('Proxy error:', err); if (!res.headersSent) { res.writeHead(500, { 'Content-Type': 'text/plain' }); res.end('Proxy error occurred.'); } }); }, }); };

Debug

Known issues

gotchaThe library internally recommends trying Next.js's native `rewrites` feature first, as it's often sufficient for basic proxying needs and requires no external libraries. Only use `next-http-proxy-middleware` if more advanced features like `onProxyInit` or complex `pathRewrite` logic are necessary.

fix

Review Next.js documentation for `next.config.js` rewrites: `https://nextjs.org/docs/api-reference/next.config.js/rewrites`.

affects: >=1.0.0

gotchaWhen using this middleware in Next.js API routes, it is critical to disable Next.js's default `bodyParser` and enable `externalResolver` in the API route's `config`. Failure to do so can lead to `Content-Type` issues for specific requests (like `multipart/form-data`) or unexpected behavior, as Next.js's body parsing interferes with the proxy's handling.

fix

Add `export const config = { api: { externalResolver: true, bodyParser: false } };` to your API route file.

affects: >=1.0.0

breakingPrior to v1.0.9/v1.0.8-hotfix.1, `http-proxy` and its types were potentially incorrectly handled or considered optional. As of these versions, `http-proxy` and its types were explicitly moved into `dependencies` to ensure correct installation and typing.

fix

Ensure `next-http-proxy-middleware` is updated to at least `1.0.9` to resolve potential dependency and typing issues with `http-proxy`.

affects: <1.0.9

gotchaVersion 1.2.4 introduced a fix for memory leaks by ensuring a new proxy instance is created for each request. Older versions might suffer from memory accumulation under high load.

fix

Upgrade to `next-http-proxy-middleware@1.2.4` or newer to benefit from the memory leak fix.

affects: <1.2.4

gotchaThe `pathRewrite` option handles patterns in the order they are entered in the array. Incorrect ordering can lead to unintended path rewrites, especially with overlapping or less specific patterns preceding more specific ones.

fix

Carefully order your `pathRewrite` patterns, placing more specific or longer patterns before more general or shorter ones to ensure desired rewrite logic is applied correctly.

affects: >=1.1.0

Errors

Common errors & fixes

Error: This expression is not callable.

Often seen in TypeScript projects when a module's default export is incorrectly typed or imported, or when an older version of TypeScript has issues with CJS/ESM interop.

fix

Ensure you are using `import httpProxyMiddleware from 'next-http-proxy-middleware';` and your `tsconfig.json` is correctly configured for your Next.js version (e.g., `"esModuleInterop": true`, `"moduleResolution": "node"`). Update `next-http-proxy-middleware` to the latest version to get the most recent type definitions. (Fix from v1.0.5 release notes).

API resolved without sending a response for /api/proxy/my-path, this may result in stalled requests.

Next.js warns when an API route handler finishes without `res.end()` or `res.json()`. Proxy middleware handles the response, so Next.js needs to know it's being handled externally.

fix

Add `export const config = { api: { externalResolver: true } };` to your API route file. This tells Next.js that an external resolver (like the proxy) will handle the response, suppressing the warning.

Error: read ECONNRESET

This typically indicates that the connection to the target proxy server was unexpectedly closed by the peer. This could be due to the target server restarting, being overloaded, or having network issues.

fix

Check the health and logs of your target proxy server (`target` option). Ensure the target URL is correct and accessible. Implement robust error handling in `onProxyInit` to log and potentially retry or respond gracefully to the client.

TypeError: Cannot read properties of undefined (reading 'on')

This error usually occurs if the `proxy` instance passed to `onProxyInit` is `undefined` or not correctly initialized, often due to an outdated or corrupted `http-proxy` dependency, or incorrect usage of `onProxyInit`.

fix

Verify that `next-http-proxy-middleware` and `http-proxy` are correctly installed and up-to-date. Ensure the `onProxyInit` callback function signature matches `(proxy: httpProxy) => { ... }` as specified in the README example.

Upgrade

Version history

1.2.8latest on npm

Audit

Dependencies

http-proxyrequiredCore functionality for proxying requests, used internally by the middleware.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/next-http-proxy-middleware ↗