- npm run dev triggers a chain of process spawning, module resolution, and file serving most developers have never fully traced.
- When you run npm run dev with Vite, your source code is never bundled — the browser fetches each file as a native ES module.
- Hot Module Replacement works by walking a lazy dependency graph, not scanning your entire codebase on every file save.
- React Fast Refresh preserves component state across edits by comparing hook signatures before deciding whether to reset anything.
Table of Contents
You’ve Typed npm run dev a Thousand Times. Here’s What’s Actually Happening
Most developers have typed npm run dev so many times it is practically muscle memory. The terminal opens, a few lines scroll past, a local address appears, and work resumes. It feels like a single command because that is exactly the abstraction it offers: start the development environment and get out of the way.
But npm itself does not have a universal “dev mode.” The command is a script entry in a project’s package configuration. In one project, it may start Vite. In another, it may launch a different development server, run a framework command, or coordinate several processes. The familiar command is less a standard feature than a convention shared across modern JavaScript projects.
That distinction matters when something breaks. “npm run dev isn’t working” can mean the package manager cannot find a script, the script cannot find an installed dependency, a process has failed to start, a port is already occupied, or the browser cannot load a module the server is expected to provide. The same short command sits on top of several layers, each with its own job.
The script is the starting gun, not the whole race
When npm receives the command, it looks for the project-defined dev script and starts the process named there. That process may in turn start other processes or invoke tooling from the project’s installed dependencies. This is one reason a project can behave differently across machines even when the command looks identical: the script and its dependency tree are part of the project, while the terminal command is merely the entry point.
Process spawning sounds like implementation trivia until a development server refuses to shut down, logs appear in an unexpected order, or an environment setting seems to vanish between commands. A parent process can launch child processes; those children can own the server, the file watcher, or a supporting task. The terminal presents it as one activity, but the operating system may be managing several related pieces of work.
Then comes module resolution. An import in application code is a request for a particular file or package. Development tooling has to interpret that request, find the appropriate source, and return something the browser can use. This is where aliases, file extensions, package entry points, and dependencies can turn a harmless-looking import error into a long debugging session. The browser sees a URL-shaped module request. The development server has to make that request meaningful inside the project.
Why Vite development feels unusually immediate
With Vite, the most important fact is also the one that runs against years of frontend habit: when you run npm run dev, your source code is never bundled. The browser fetches each file as a native ES module.
That changes the shape of the development loop. Traditional frontend workflows often treated bundling as the central event. A tool gathered application code and dependencies, produced one or more browser-ready assets, and served the result. Any meaningful change could involve rebuilding that output before the browser could see it.
Vite moves the emphasis. During development, the server responds to the browser’s module requests rather than requiring the whole application to be assembled into a bundle first. The browser requests an entry module, encounters its imports, and requests those modules in turn. The server is still doing essential work: serving files, resolving imports, and making modules usable in the development environment. It is not absent from the process. It simply is not waiting to construct a single all-encompassing application bundle before the page can start.
The practical benefit is not mystical speed. It is narrower work. If a developer changes one component, the system can focus on the modules connected to that change instead of treating the entire source tree as a fresh bundling problem. That is especially valuable in projects where the difference between changing a file and seeing the result determines whether experimentation feels natural or costly.
Hot updates are targeted, not magical
Hot Module Replacement is often described as if the page somehow notices a change and fixes itself. The real mechanism is more disciplined. It works by walking a lazy dependency graph, not scanning your entire codebase on every file save.
A dependency graph is the map formed by imports: this module depends on that module, which depends on another. It is “lazy” in the useful sense that the development environment can work from the modules that have actually entered the running application’s world rather than repeatedly treating every file in the repository as equally relevant. When a file changes, the tool can trace the effect through that graph and determine where an update can be accepted.
That is why some edits appear almost instantly while others trigger a broader reload. A change that stays within a boundary the running application can replace is a good candidate for a hot update. A change that affects a module more fundamentally may require the browser to reload more of the application. Neither outcome is a failure. They reflect the limits of replacing code in a live program without leaving it in an inconsistent state.
The dependency graph also explains why import structure has consequences beyond code organization. Clean boundaries can make the path of an update easier to reason about. Tangled dependencies can make a small edit reach farther than expected. Developers do not need to design every component around HMR, but understanding that updates follow relationships between modules makes the occasional “why did this reload everything?” moment less mysterious.
Fast Refresh protects state when it can justify doing so
React Fast Refresh adds another layer to the experience. It is the reason a component edit can appear in the browser without automatically wiping out the local state a developer was using to test an interaction. That convenience can feel like a minor quality-of-life feature until a form, menu, or in-progress UI state survives an edit that would otherwise force the developer to recreate it.
Still, state preservation is conditional. React Fast Refresh preserves component state across edits by comparing hook signatures before deciding whether to reset anything. The important word is “before.” It is not blindly retaining whatever state happened to be present. It is checking whether the updated component remains compatible enough with the existing stateful shape.
If that shape changes in a way React cannot safely reconcile, resetting is the honest result. A preserved state value attached to the wrong logical place would be worse than a refresh. The occasional reset is therefore not proof that Fast Refresh is unreliable; it is evidence that the system is refusing to pretend an edit is harmless when it may not be.
The broader lesson is that npm run dev is useful precisely because it hides complexity, not because the complexity is gone. A script starts a tool. The tool starts processes, resolves modules, serves code, watches for changes, and communicates with the browser. Vite avoids bundling source code in development by leaning on native ES modules. HMR follows the dependency graph. React Fast Refresh makes a careful decision about state rather than a wishful one.
Once that mental model clicks, development-server behavior becomes easier to diagnose. A missing import is a module-resolution problem. A full reload after an edit may be a boundary issue. Lost React state may follow a hook-signature change. The command remains short, thankfully. But it no longer has to be magic.
