Next.JS — How To Proxy To Backend Server

Explaining how to configure a proxy for backend API calls with an example.

Bhargav Bachina
Aug 16, 2020 · 6 min read
Photo by Jakob Creutz on Unsplash

There are so many ways we can develop and deploy React application. Mostly we are deploying React applications in serverless mode nowadays. Next.js is a React Framework for production. Next.js gives you the best developer experience with all the features you need for a production environment such as hybrid static & server rendering, TypeScript support, smart bundling, route pre-fetching, and more. No config needed.

When you have an API with NodeJS and deploying with it in the production you can build and deploy without any issues. But, when it comes to the development environment you have to configure a proxy to redirect all the API calls from the Next.js App.

What is proxying

In general, A proxy or proxy server serves as a gateway between your app and the internet. It’s an intermediate server between client and servers by forwarding client requests to resources.

In Next.js, we often use this proxying in the development environment. Next.js is a React framework. If we look at the following diagram, app UI is running on port , and the backend server is running on port . All the calls start with will be redirected to the backend server and rest all fall back to the same port.

In subsequent sections, we will see how we can accomplish this and other options as well.

proxying all URLs start with /api

Example Project

Here is an example project with the Github link you can clone it and try it on your machine.

// clone the project
git clone
// Run the API
cd api
npm install
npm run dev
// Run the Next.JS App
cd todo-app
npm install
npm run dev

Once you install all the dependencies, you can start both the Next.js app and node js server on and respectively.

You can start the Next.js app with these commands npm run dev or next devand here is the Next.js app running on

An app running on port 3000

Let’s start the server with this command npm run devand test this API on port .

What is Custom Server

If you are familiar with the react library we can set up a proxy with the proxy object in the package.json like below.

"proxy": "http://localhost:3080"

Even though Next.js is React framework it doesn't work that way at the time of writing. Typically you start your next server with next start. It's possible, however, to start a server 100% programmatically in order to use custom route patterns.

Then, to run the custom server you’ll need to update the scripts in package.json. You can find more about this on their site.


Proxy Setup

We can set up a proxy with the help of a custom server. We need to install http-proxy-middleware in the Next.js UI.

npm install http-proxy-middleware --save

Here is the custom file where we are using http-proxy-middleware to proxy all the calls with context path /api. We are proxying only if it is a development environment and all other requests will be redirected to Next.js router.


Here is the package.json file of Next.js App and we are using server.js with the command npm run dev. Here are the instructions to run the app in the local environment.

// on Terminal 1cd todo-app
npm run dev
// on Terminal 2cd api
npm start

Here is the App running on the port 3000 and all the API calls are proxying to the port 3080.

App working with proxy

How To Proxy to Multiple APIs

We have seen how we can proxy into one API from your Next.js UI. This is not the case most of the time. Your Next.js app might need to call multiple APIs to get the data. Let’s see how we can do that.

For example, if you look at the below diagram the Next.js UI is calling two APIs: and . All the calls that start with should be redirected to and all the calls that start with the should be redirected to

proxy for multiple APIs

We can implement this scenario with the custom serverI have added one more API with the context path api2 andwe need to add one more middleware entry as shown in the file.

Multiple Entries

In the api2 API we have the same functionality but running on a different port 3081. Here is the server.js file from api2.

api2 server.js

Let’s test these two APIs from the .

Proxy in action

Rewrite the Path URL

Whenever there is a change in the URLs, we often rewrite the path of the backend server endpoints. We can do that with the pathRewrite.

Let’s understand the option. For instance, our backend URL /api/todos is changed to /api/tasks/todos and we want to test in development before it goes to production. We can achieve this with the option like below.


Multiple app entries to one API endpoint

Sometimes we have multiple modules with services in our app. We might have a scenario where multiple entries or services will call the same API endpoint.

For example, we have two paths that are needed to be redirected to the same endpoint (line 19). This is possible with the following setup.


Now if you hit both URLs in the browser http://localhost:3000/api/todos and http://localhost:3000/api2/todos both will be redirected to the same API.

Multiple app entries to one API endpoint


  • In React, the create-react-app proxy is used mostly in the development environment to facilitate the communication between server and UI.
  • Even though Next.js is a react js framework, it doesn’t work that way.
  • We need to set up a custom server manually in Next.js applications. Next.js doesn't recommend custom servers for production environments.
  • We need to have a backend server and UI running on different ports.
  • The proxy entry should be added to the file that is redirected to API calls based on the URL.
  • We need to make sure the Next.js App and Backends are running on different ports for successful communication.
  • We need to install for the customized setup.
  • We can rewrite the path with the option
  • We can proxy multiple entries to one backend API with it as well.
  • We can proxy multiple entries to multiple backends as well with multiple entries in the middleware.


This is an excellent feature for the development phase. If you are working on the Next.js application, this feature really speeds up your development. You need to limit this feature only for development. Next.js doesn’t recommend this for production environments.

Bachina Labs

Tutorials Ranging from Beginner guides to Advanced | Never…

Sign up for BB Tutorials & Thoughts

By Bachina Labs

Tutorials Ranging from Beginner guides to advanced on Frontend, Backend, Blockchain, Docker, k8s, DevOps, Cloud,AI, ML. Thank you for subscribing and let me know if you want me cover anything?  Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Bhargav Bachina

Written by

Software Architect — Sharing Experiences With Examples | Frontend, Backend, Blockchain, Docker, k8s, DevOps, Cloud,AI, ML |

Bachina Labs

Tutorials Ranging from Beginner guides to Advanced | Never Stop Learning

Bhargav Bachina

Written by

Software Architect — Sharing Experiences With Examples | Frontend, Backend, Blockchain, Docker, k8s, DevOps, Cloud,AI, ML |

Bachina Labs

Tutorials Ranging from Beginner guides to Advanced | Never Stop Learning