What Is npm run dev? A Beginner-Friendly Command Explanation

npm run dev is a command used by many modern web projects to start a local development server on your own computer.

In plain English, it usually means:

"Start my project in development mode so I can view it in the browser while I work on it."

If you are learning to build websites or apps with tools like Next.js, React, Vite or similar frameworks, you will probably use npm run dev often. It is one of the first commands beginners meet when they start building locally.

This guide explains what the command does, why it matters, what happens behind the scenes, and what to do if it does not work.

The short answer

npm run dev tells npm to run the project's dev script.

That script is usually defined inside a file called package.json.

For example, a Next.js project might have this inside package.json:

{
  "scripts": {
    "dev": "next dev"
  }
}

When you run:

npm run dev

npm looks inside package.json, finds the script called dev, and runs the command attached to it. In this example, that command is:

next dev

That starts the Next.js development server.

What happens when you run npm run dev?

Most beginner-friendly web projects follow the same basic pattern.

You open the terminal.
You move into your project folder.
You run npm run dev.
The project starts a development server.
The terminal shows a local URL, often something like http://localhost:3000.
You open that URL in your browser.
You keep the server running while you edit your project.

The important idea is that your website is not being published to the internet yet. It is running on your own computer so you can build and test safely.

What is localhost?

localhost means your own computer.

When a project says:

Local: http://localhost:3000

it means your browser can view the project at that address while the development server is running.

The number at the end, such as 3000, is the port. A port is like a numbered doorway that lets your browser talk to the local server.

So localhost:3000 means:

"Open the project running on my own computer through port 3000."

Why beginners use npm run dev

npm run dev is useful because it gives you a fast feedback loop.

Instead of changing code, publishing the site, and hoping it works, you can:

edit a file
see the result locally
notice errors quickly
ask AI for help with a specific problem
test the change again

That is the heart of local development. You build on your own machine first, then think about deployment later.

Is npm run dev the same in every project?

No. The command looks the same, but the script behind it can be different.

One project might use Next.js:

{
  "scripts": {
    "dev": "next dev"
  }
}

Another project might use Vite:

{
  "scripts": {
    "dev": "vite"
  }
}

In both cases, npm run dev means "run the dev script", but the tool being started is different.

Where should I run npm run dev?

Run npm run dev from the root folder of the project. That is usually the folder that contains package.json.

If you run it from the wrong folder, npm may not know which project you mean.

A simple check is:

ls

On Windows PowerShell, you can also use:

dir

You are looking for a file called package.json. If you can see it, you are probably in the right place.

Do I need to run npm install first?

Usually, yes.

Before npm run dev can work, the project dependencies need to be installed. That usually means running:

npm install

This reads package.json and downloads the packages the project needs. Those packages usually include Node.js tools, framework packages, and development utilities.

After that, you can run:

npm run dev

Common npm run dev errors

Missing script: dev

If you see an error like:

Missing script: "dev"

it means npm could not find a script called dev inside package.json.

Check the scripts section. It might look like this:

{
  "scripts": {
    "start": "next start"
  }
}

In that case, there is no dev script for npm to run.

Command not found

If the terminal says a command is not found, dependencies may be missing or the project may not be set up yet.

Try:

npm install

Then run:

npm run dev

again.

Port already in use

If you see a message saying the port is already in use, another development server may already be running.

You can either stop the old server or use the new URL your framework suggests. Some tools automatically move from port 3000 to 3001 if 3000 is busy.

The page does not load in the browser

Check that the terminal still shows the development server running. If you closed the terminal or stopped the server, the localhost page will stop working.

You can usually restart it with:

npm run dev

npm run dev vs npm run build

npm run dev is for working locally while you build.

npm run build is usually for preparing the project for production.

A simple way to think about it:

npm run dev starts the project for development.
npm run build checks and prepares the project for release.
production is the live version users actually visit.

Beginners usually spend most of their early time with npm run dev, because that is where they can safely test changes.

npm run dev vs staging and production

Your local development server is not the same as a staging environment or production website.

Local development happens on your own machine.

Staging is a more realistic test version, often online but not intended for normal users.

Production is the real live site.

The usual journey is:

Build locally with npm run dev.
Save your work with version control.
Deploy to staging or preview.
Check everything carefully.
Release to production when ready.

How this fits into learning to code with AI

When you use AI to help build a project, npm run dev becomes part of the feedback loop.

You can ask AI for a small change, apply it, run the project locally, inspect what happened, and then ask a better next question.

That is much safer than asking AI for a large finished app in one go.

At Vibe Code Academy, this is the kind of workflow beginners practise from the start: small steps, local testing, clear errors, and steady improvement.

Quick checklist

Before running npm run dev, check:

you are in the project folder
package.json exists
dependencies have been installed with npm install
no other server is already using the same port
you keep the terminal open while working