package.json (npm run) scripts

We used the dev script earlier, but where does this script come from?

The scripts are in our package.json file (which is located in the root of our project). A package.json can have a scripts object where we can add commands that we will use often.

The scripts object contains one or more key/value pairs. The key is an alias we will use instead of the full command, and the value is the command itself.

Using npm run scripts has the advantage of not needing to type (or even remember) the full command but only the alias. As the package.json is part of our project and because we commit it to our repository, everyone that will be working on our project will be able to use those commands too.

There are a few aliases for scripts that will make your commands even shorter, start is one of those so called lifecycle scripts, if you add a start script (like the one we have in our package.json) allows you to use the short version npm start (compared to the longer version npm run start)

How to use (npm run) scripts

All npm run SCRIPT_NAME commands work because they have been added to the package.json scripts block. In our case, the npm run dev we used earlier works because create next app has added it to the package.json for us:

Here is the full scripts section Next.js 15 added to our package.json:

"scripts": {
    "dev": "next dev",
    "dev-turbo": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
},

To get a list of all scripts without opening the package.json, you can use the following command:

npm run

This will show you the 5 commands added by create next app.

Edit / add run scripts

To edit (or even add) run scripts, we first need to open our package.json file (which is in the root of the project)

Changing the Next.js dev server port

As you may have noticed, when we used npm run dev, it started the dev server using port 3000. This is because port 3000 is the default port used by Next.js. If port 3000 is already in use, Next.js will use the next best free port, so for example, port 3001, 3002, 3003...

You can, however, also change the port manually if needed. To do so, you need to use the -p option and add it to the dev command (this option also works for the start command, used to start the production server)

For example, to use port 4000, edit your package.json and change next dev to this:

    "scripts": {
        "dev": "next dev -p 4000",
    },

Then run the npm command to execute that script like so:

npm run dev

You will see that now Next.js uses the port you have told it to use because the address it prints in the terminal is now using port 4000:

  - Local: http://localhost:4000

Changing script options without editing the script in the package.json

In some situations you don't want to edit your package.json and prefer a more dynamic solution, for such situations there is an alternative way, it is just a bit longer, but adds flexibility you might need at some point, and the result will be the same as the one we got in the previous chapter, a development server running on port 4000

In our run script we use two hyphen (--) tho indicate that it is the end of the run script options, every argument we add after will get passed to the script itself

For example to launch the dev server on port 4000 without editing the package.json we could us this command:

npm run dev -- -p 4000

Or to start the production server:

npm start -- -p 4000

Next.js CLI commands and NPM npx

When using a command like npm run dev, npm will check for a script alias and then execute the corresponding command. In the case of npm run dev, it will execute next dev

next dev is a Next.js CLI command to start the development server. There are other Next.js CLI commands you can use, like next build, next start, next lint, and a bunch more

If you try to use those commands in the terminal (or your favorite command line tool), for example:

next dev

On Linux, you will get an error like this:

bash: next: command not found

On Windows in PowerShell, you will get an error like this:

The term 'next' is not recognized as the name of a cmdlet, function, script file, or operable program. (...)

This is because your operating system does not know where to find the next cli

To fix this, we can use NPMs npx like so:

npx next dev

and now everything works as expected

Next.js CLI options

For example, this command will show the options for the Next.js dev CLI:

npx next dev -h

Or to see the options of the linting command, use:

npx next lint -h

Besides starting the dev server, there are other interesting CLI commands you may want to try out at some point. For example, if you have a build that fails during deployment and you want to debug that build of your project locally, then you can use this command:

npx next build --debug

After the build is done, Next.js 15 will print a lot of interesting information in your terminal, like what headers, rewrites, redirects, routes, … are in your app. It will also add information like: did this page get prerendered as static content, or is it dynamic and will get rendered at runtime.

Another command to get some information about your system is:

npx next info

Adding new commands to our package.json scripts

After experimenting with Next.js CLI in your terminal, you can of course, add those to your package.json, too.

Adding them to your package.json scripts has the advantage that you don't need to remember them, and it has the advantage that when other devs join your project, they can use them, too.

To add the info CLI command to your package.json, open the package.json and edit it like this:

    "scripts": {
        "dev-4000": "next dev -p 4000",
        "info": "next info",
        "build-debug": "next build --debug",
    },

Because we use the command as a script (in our package.json), we do NOT need to use npx anymore, as NPM does it (under the hood) for us.

Next.js development server HTTPS (localhost SSL certificate)

There is one last dev CLI option I want to highlight before we go back to our project, which is --experimental-https

The next dev command always starts a dev server using HTTP, but there are situations where you want to use HTTPS instead.

The great thing about --experimental-https is that Next.js will download an extra package that it will then use to create and set up a self-signed certificate for our localhost.

All we need to do is that option to our next dev command like so:

npx next dev --experimental-https

This will start your dev server using HTTPS, and you can see a recap of what Next.js did for you in your terminal, something like this:

⚠ Self-signed certificates are currently an experimental feature, use with caution. Attempting to generate self signed certificate. This may prompt for your password CA Root certificate created in C:\Users\xxxx\AppData\Local\mkcert Certificates created in C:\Users\xxxx\grepos\test\certificates Adding certificates to .gitignore

This message lists all the things Next.js just did for you, it created a self signed SSL certificate and added the folder containing the certificate to your .gitignore because the certificate is only for your local development and should NOT get committed (shared)

You can now visit your localhost with SSL at https://localhost:3000/