npm run dev vs npm run build: why your agent runs one to code and the other to ship

What it actually is

dev and build are just script labels inside your project’s package.json, but nearly every starter (Next.js, Vite, Create React App) uses them the same way, so they’ve become a convention everyone expects. npm run dev starts a local server tuned for speed of iteration: it reloads the page (or just the piece you changed) the instant you save a file, keeps the code unminified so error messages point at real, readable line numbers, and skips optimizations that would only slow you down while you’re still changing things every few seconds. npm run build does something completely different: it doesn’t start a server at all. It’s a one-time compile pass that reads your whole project, strips out anything dev-only, minifies your JavaScript and CSS, and writes the result into an output folder, .next for Next.js, dist for Vite.

Think of it like cooking at home while tasting as you go, adjusting salt, checking the pan, versus running that recipe through an industrial kitchen once to package it for shipping: sealed, labeled, meant to survive a truck ride without you standing over it. You don’t reopen the sealed box to taste it. If something’s off, you fix the recipe and run it through again.

Why your AI just did this

When you ask your agent to show you something, it runs npm run dev (or it’s already running in the background), because that’s the fastest way for both of you to see a change instantly. When you say “ship it,” the job changes: either your agent runs npm run build itself, or your hosting platform runs it automatically the moment you push, as part of the deploy pipeline. Either way, the goal shifts from “fastest feedback for you” to “smallest, most correct file possible for real visitors.”

This is also why an agent sometimes says “let me run a production build to check first”: npm run build is stricter. It runs full type-checking that the dev server skips to stay fast, so the errors it turns up are worth fixing before you deploy.

When you’ll run into it

• Terminal prints ready on http://localhost:3000 after npm run dev. Nothing comparable happens after npm run build, it just finishes and hands control back to your prompt; it never serves anything by itself.
• A Vercel or Netlify deploy log showing a step labeled Running "next build" or Running "vite build", that’s this same command, just triggered by the platform instead of you.
• A bug that never showed up while you were testing with npm run dev, but appears the moment you deploy, usually a TypeScript error or a page that only fails once it gets statically pre-rendered, both things the strict build catches and the loose dev server doesn’t.
• Opening the dist or .next folder directly in a browser and finding nothing works. That output is static files, not a running app; you need vite preview, next start, or a real host to actually serve it.

What to check

• Confirm which command actually failed by reading the log carefully. “It works in dev” and “it works after a build” are two separate, unrelated facts
• The output folder (dist, .next, build) is listed in .gitignore. It’s generated fresh every time, never something you hand-edit or commit
• Before trusting a fix is real, test it against an actual production build (npm run build then npm start or vite preview), not just the dev server
• If a deploy’s build step fails, read the first real error in the log, not just the red “failed” line above it
• Your hosting platform’s build command matches your framework’s convention (next build, vite build); most platforms auto-detect this, but a custom package.json script name can break that detection

Say it like a dev

Instead of: “why does it look different once it’s online” Say: “did we test this against a production build, not just the dev server?”

Instead of: “the build is broken” Say: “npm run build is failing, is it a type error or a missing environment variable?”

Instead of: “just start the app so I can see it” Say: “run it in dev mode” (or “run the production build” if that’s specifically what’s needed)