Next.js HTTP Proxy Middleware

Common errors

• Error: This expression is not callable.

  cause 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.

  cause 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

  cause 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')

  cause 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.

Warnings

• gotcha The 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`.
• gotcha When 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.
• breaking Prior 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`.
• gotcha Version 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.
• gotcha The `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.

Install

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

Imports

• httpProxyMiddleware
  wrong:

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

  correct:

  import httpProxyMiddleware from '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
  wrong:

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

  correct:

  import type { 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`.

Quickstart

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.');
        }
      });
    },
  });
};