next-http-proxy-middleware

Next.js HTTP Proxy Middleware

HTTP Proxy middleware available in API Middleware provided by Next.js.

⭐️ Before using

Please try the solutions below before using this library. 😀

Try using Next.js Rewrites(recommended)

• This function is supported by Next.js. No additional libraries need to be installed!
  • https://nextjs.org/docs/api-reference/next.config.js/rewrites

  // next.config.js
  async rewrites() {
   return [
     {
       source: "/api/:path*",
       destination: "http://example.com/api/:path*",
     },
   ];
  },
  

Try using Http-Proxy

• next-http-proxy-middleware is implemented using http-proxy internally. Since the implementation is not complicated, it is recommended to try http-proxy directly.

  // pages/api/[...all].ts
  import httpProxy from "http-proxy";
  
  export const config = {
    api: {
      // Enable `externalResolver` option in Next.js
      externalResolver: true,
      bodyParser: false,
    },
  };
  
  export default (req, res) =>
    new Promise((resolve, reject) => {
      const proxy: httpProxy = httpProxy.createProxy();
      proxy.once("proxyRes", resolve).once("error", reject).web(req, res, {
        changeOrigin: true,
        target: process.env.NEXT_PUBLIC_API_PROXY_URL,
      });
    });
  

Installation

The easiest way to install next-http-proxy-middleware is with npm.

npm install next-http-proxy-middleware

Alternately, download the source.

git clone https://github.com/stegano/next-http-proxy-middleware.git

Features

This middleware is implemented using the http-proxy library. You can use the existing options provided by http-proxy. And you can rewrite the api path using pathRewrite, an additional option provided by this middleware.

• http-proxy options

pathRewrite option

• Replaces URL information matching the pattern with another string.
  • Priority is determined in the order entered in the array.
  • If the request URL matches the pattern pathRewrite.patternStr replace the URL string with the value pathRewrite.replaceStr.

onProxyInit option

• You can access the http-proxy instance using the onProxyInit option. See the example below.

  import type { NextApiRequest, NextApiResponse } from "next";
  import type { NextHttpProxyMiddlewareOptions } from "next-http-proxy-middleware";
  import httpProxyMiddleware from "next-http-proxy-middleware";
  
  const handleProxyInit: NextHttpProxyMiddlewareOptions["onProxyInit"] = (proxy) => {
    /**
    * Check the list of bindable events in the `http-proxy` specification.
    * @see https://www.npmjs.com/package/http-proxy#listening-for-proxy-events
    */
    proxy.on("proxyReq", (proxyReq, req, res) => {
      // ...
    });
    proxy.on("proxyRes", (proxyRes, req, res) => {
      // ...
    });
  };
  
  export default async (req: NextApiRequest, res: NextApiResponse) =>
    httpProxyMiddleware(req, res, {
      target: "http://example.com",
      onProxyInit: handleProxyInit,
    });
  

Example

• Refer to the following for how to use Next.js API Middleware

  • Next.js API Middlewares Guide

  // pages/api/[...all].ts
  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
      externalResolver: true,
    },
  }
  
  export default (req: NextApiRequest, res: NextApiResponse) => (
    isDevelopment
      ? httpProxyMiddleware(req, res, {
        // You can use the `http-proxy` option
        target: "https://www.example.com",
        // In addition, you can use the `pathRewrite` option provided by `next-http-proxy-middleware`
        pathRewrite: [{
          patternStr: "^/api/new",
          replaceStr: "/v2"
        }, {
          patternStr: "^/api",
          replaceStr: ""
        }],
      })
      : res.status(404).send(null)
  );
  

  • externalResolver is an explicit flag that tells the server that this route is being handled by an external resolver. Enabling this option disables warnings for unresolved requests.
    • See the issues below
      • https://github.com/stegano/next-http-proxy-middleware/issues/32
      • https://github.com/stegano/next-http-proxy-middleware/issues/21

Using multipart/form-data

⚠️ Important: When handling multipart/form-data requests (e.g., file uploads), you must disable Next.js's built-in bodyParser in your API route. By default, Next.js parses the request body, which corrupts binary file content in multipart requests.

Add the following configuration to your API route:

export const config = {
  api: {
    bodyParser: false,
    // Enable `externalResolver` option in Next.js
    externalResolver: true,
  },
};

• For more details, refer to the resources below:
  • Next.js Custom Config for API Routes
  • https://github.com/stegano/next-http-proxy-middleware/issues/33
  • https://github.com/vercel/next.js/pull/7686

Other projects

• ReactRenderStateHook
  • react-render-state-hook is a React hook that enables declarative management of components based on data processing states. It facilitates straightforward state management and data sharing among multiple components in a React.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Denny Lim 🐛 💻	Kristian Tryggestad 🐛 💻	Gunnlaugur Thor Briem 💻 🤔	Otto von Wesendonk 🛡️	Daniel Silva 🤔	Yann Pringault 💻	Lorenzo 📖
Timon Grassl 🐛	Abhinav Kumar 📖	Jack Cuthbert 📖	Vytenis 📖	Dario Varotto 📖	johannbrynjar 🐛 💻	bever1337 📖
itniuma 📖

This project follows the all-contributors specification. Contributions of any kind welcome!