Configure Next.js Dev Mode to Run on a fixed Port

When working with Next.js, the default port for the development server is set to 3000. While this is convenient for many projects, there are times when we need to run our application on a different port, such as 5000. Maybe it’s a port conflict, or perhaps it’s just a personal preference. Whatever the reason, configuring Next.js to run on a different port is a simple and effective way to customize your development environment.

Thank me by sharing on Twitter 🙏

In this post, I’m going to walk through how to configure Next.js to run on port 5000 during development. This involves making small adjustments in how we start the server, and we’ll cover different ways to achieve this.

Why Change the Default Port?

Before diving into the configuration process, it’s worth considering why someone might want to change the default port. Here are a few common reasons:

  • Port Conflicts: You may already have another service running on port 3000 (e.g., another development environment, a local API, or a React app). Changing the port allows both services to run simultaneously without interference.
  • Custom Environment: In larger teams or when following certain organizational standards, you may have a predefined set of ports allocated for specific services. Changing the port helps maintain consistency across different environments.
  • Multiple Instances: If you’re working on multiple Next.js projects at once, changing the port on one of the instances can avoid conflicts and keep things organized.

Now that we’ve explored the “why,” let’s get into how you can change the port for your Next.js development environment.

Using the Command Line to Specify a Port

One of the quickest ways to change the port for your Next.js app is by using the command line. When running the Next.js development server, we can pass a -p flag followed by the desired port number.

For example, to run the app on port 5000, you can execute the following command:

Plaintext
next dev -p 5000

This tells Next.js to start the development server on port 5000 instead of the default 3000. The great thing about this method is its simplicity—it’s ideal for one-off use cases or when you need to quickly switch between ports without modifying any configuration files.

If you’re using TypeScript for the build process, the same command applies. However, if you’re running scripts through npm or yarn, you might want to modify the package.json to streamline this process further.

Modifying the package.json Script

When you’re constantly switching to a specific port, updating the command every time can become repetitive. A better approach is to modify the scripts in your package.json so that the Next.js development server runs on the port you specify by default.

In the root directory of your project, open the package.json file and look for the scripts section. You’ll find something like this:

JSON
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

To make the development server start on port 5000 automatically, modify the dev script as follows:

JSON
{
  "scripts": {
    "dev": "next dev -p 5000",
    "build": "next build",
    "start": "next start"
  }
}

Now, whenever you run npm run dev or yarn dev, the Next.js development server will launch on port 5000 without needing to manually specify the port each time.

This is a great solution when you’re working on the same project regularly and need to ensure that it always runs on a specific port.

Setting a Port Using Environment Variables

Another common approach is to use environment variables to configure the port. This method is particularly useful if you have different environments (e.g., local, staging, production) that each require different configurations.

In Next.js, you can set environment variables in a .env file. If you don’t already have one, create a .env file in the root of your project, and add the following line to set the port:

Plaintext
PORT=5000

Next.js will read from this .env file and use the specified port when you run the development server. This approach is especially useful in a collaborative environment, where you can define various settings in the .env file, and the whole team benefits from the shared configuration.

Once you’ve added the port to the .env file, run the development server as usual:

ShellScript
npm run dev

Or, if you prefer using yarn:

ShellScript
yarn dev

Since the port is now set in the environment file, Next.js will automatically pick it up and start the server on port 5000.

Setting the Port Directly in the Terminal

If you prefer not to modify the package.json or create a .env file, you can also set the port directly from the terminal when starting the development server. This can be done by defining the PORT environment variable inline with your npm or yarn command.

For macOS and Linux, you can run:

ShellScript
PORT=5000 npm run dev

Or for yarn:

ShellScript
PORT=5000 yarn dev

On Windows, the syntax differs slightly:

ShellScript
set PORT=5000 && npm run dev

This method gives you the flexibility to specify a different port each time you run the development server, which is ideal if you’re working on multiple projects simultaneously or need to switch ports frequently for testing purposes.

Conclusion

Changing the development port in Next.js is a simple but essential customization that can help you avoid conflicts and maintain a smoother development workflow. Whether you opt to use the command line, modify your package.json, or configure a .env file, there are multiple ways to achieve the same goal, each with its own advantages.

For quick changes, the -p flag works perfectly. If you want to automate things a bit more, updating the package.json script or using a .env file is the way to go. And for those times when you need absolute flexibility, setting the port directly in the terminal ensures that you’re always in control.

With this knowledge, you can easily adapt your Next.js setup to fit your project’s needs, no matter how complex your development environment becomes.

Share this:

Leave a Reply