npm run dev vs npm run build: What’s the Difference? (Next.js + Vercel)

Why your site works locally but fails on Vercel, and how to catch it before you deploy.

Has this happened to you? Your Next.js app runs perfectly with npm run dev. You push to GitHub, and then Vercel shows “Build Failed”.

I have been there. The fix is simple once you understand what npm run dev and npm run build actually do. Let’s go step by step.

What Does npm run dev Do?

npm run dev starts the development server. It is made for coding, so it is fast and friendly:

• It refreshes your page when you save a file (hot reload)
• It shows helpful error messages
• It does not fully optimize your code

Think of it as a rehearsal. Things can look fine here and still break on the real stage.

What Does npm run build Do?

npm run build creates the production version of your app. Next.js checks your code, compiles it, optimizes it, and saves the result in the .next folder.

If your code has a TypeScript error or another build problem, the build fails. That is a good thing, because you find the bug before your users do.

Think of it as the final exam before going live.

What Does Vercel Do Behind the Scenes?

Here is the good news. You don’t have to run npm run build by hand every time. Vercel does it for you:

1. You push code to GitHub. Vercel gets a signal that new code arrived.
2. Vercel downloads your code from the repository.
3. Vercel runs npm run build on its own cloud server.
4. Vercel checks the result. If there is an error, the build fails and your live site stays unchanged. If everything is fine, the .next output is ready.
5. Vercel makes it live on the internet.

That “Building…” message you see on the Vercel dashboard is your npm run build command running. This whole flow is called a CI/CD pipeline, and most modern frontend teams work this way.

When Should You Run npm run build on Your Computer?

Only in two cases.

Case 1: Check for errors before you push (recommended)

Sometimes npm run dev works fine but Vercel fails. To avoid this, run the build locally first:

Get Mohib Ali Khan’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

cmd

npm run build

If it passes on your machine, it will most likely pass on Vercel too. This saves you time and avoids failed deployments.

Case 2: Test real production performance

Your site can behave differently in production. Speed and even styling (like CSS order) may not match what you see in dev mode. To see how your live site will really look, run these two commands:

cmd

npm run build
npm run start

• npm run build creates the optimized production version
• npm run start runs it locally in production mode

Now open http://localhost:3000 and you are seeing the real thing.

Quick Comparison

Final Thoughts

You don’t need to build manually every time, because Vercel does it automatically. But a smart developer runs npm run build before pushing, so a failed deployment never surprises them.

Simple rule: dev for coding, build + start for checking, and Vercel for going live.

If this helped you, give it a clap 👏 and follow me for more Next.js tutorials.