In an npm project, how does `npm run build` run `vite build` when Vite is only a devDependency and not installed globally?
answer
- where installed commands get linked
- each dependency's bin field
- the PATH a script is given
- node_modules/.bin added for scripts only
- npx or npm exec from a terminal
basics
~20 snpm links every command a dependency declares in its bin field into node_modules/.bin, and npm run adds that folder to the PATH it gives each script, so vite resolves to the project's own installed copy.
solid answer
~40 sWhen `npm install` places a package that declares a `bin` field, npm links each command into `./node_modules/.bin` — a symlink on Unix-like systems, a `.cmd` shim on Windows. `npm run` then adds `node_modules/.bin` to the `PATH` it hands the script, on top of the shell's own `PATH`, so the script line `vite build` finds the Vite installed for this project: no global install, and every teammate and CI run uses the version the project installed. The same environment applies to `npm test`, `npm start` and lifecycle scripts. Typing `vite` straight into a terminal fails because your shell's `PATH` never changed; use `npx vite` or `npm exec -- vite` there. If the script itself says `vite: not found`, look at the install: dependencies missing, devDependencies omitted with `--omit=dev`, or `--no-bin-links`.
go deeper
Recall the two halves: install links each bin command into node_modules/.bin, and npm run puts that folder on the PATH of the script. Then name npx as the way to call the same tool from a terminal.
Explain the script environment as a whole: the extra PATH entry, the package-root working directory, INIT_CWD and the npm_ variables, plus symlinks versus .cmd shims and what bin-links controls.
Diagnose a command that works on one laptop and not in CI: a hidden global install, an install with devDependencies omitted, or bin links switched off. Argue for declaring every build tool as a devDependency.
Frame local binaries as a reproducibility contract: the lockfile fixes which tool version every build runs, and anything a build needs from outside node_modules is an undeclared dependency the team will rediscover on a fresh runner.
## What `node_modules/.bin` is Many npm packages ship a command-line program. A package announces its commands through the **`bin` field** of its own `package.json`: a map from command name to a file inside the package, or a single string when the command carries the package's name. When `npm install` places such a package in a project, npm creates one entry per command in **`./node_modules/.bin`**: - on Unix-like systems the entry is a **symlink** to the package's script; - on Windows npm writes a **`.cmd` shim** that runs the script; - the `bin-links` config (default `true`) controls this step, so `--no-bin-links` skips it. This happens for every installed dependency that declares commands, **devDependencies included**. That is why a build tool such as Vite, declared only under `devDependencies`, still ends up with a `node_modules/.bin/vite` entry after a normal install. ## How `npm run` builds the script's environment `npm run <name>` reads the `scripts` field and starts the matching line in a shell (`/bin/sh` on POSIX systems, `cmd.exe` on Windows, changeable with the `script-shell` config). Before it does, it prepares the environment: 1. It keeps the shell's existing `PATH`. 2. It **adds the project's `node_modules/.bin`** to that `PATH`. 3. It sets variables such as `npm_lifecycle_event`, `npm_package_name`, `npm_package_version` and `INIT_CWD`. 4. It runs the script from the **package root**, whatever directory you typed the command in. Because of step 2, the script line `"build": "vite build"` finds the project's own Vite. No global install is involved, and every teammate and every CI run uses the copy installed for this project rather than whatever happens to be on the machine. The same environment is used for `npm test`, `npm start` and the lifecycle scripts npm runs itself, which is why npm's own documentation tells you to write `"test": "tap test/*.js"` rather than spelling out `node_modules/.bin/tap`. To see that environment for yourself, `npm run env` prints the variables a script would receive, the extended `PATH` included. ## Running the same binary outside a script Your interactive shell never received that `PATH` change, so typing `vite build` at the prompt usually ends in "command not found". There are several ways to reach the local copy: | Invocation | What happens | |---|---| | `npm run build` | runs the script, with `node_modules/.bin` on `PATH` | | `npx vite build` | runs the locally installed `vite` when the project has it; otherwise prompts before fetching it | | `npm exec -- vite build` | the same command as `npx`; the `--` ends npm's own option parsing | | `./node_modules/.bin/vite build` | calls the link directly | `npx` is the everyday choice. When the package is already installed in the project, neither `npx` nor `npm exec` downloads anything. ## When the command is not found inside a script If `npm run build` itself reports that `vite` cannot be found, the cause is almost always on the install side, not in the script line: - dependencies were never installed in this clone (npm adds a hint to run `npm install` when a script fails and there is no `node_modules`); - the install left devDependencies out, for example with `--omit=dev` in a production image that still runs the build; - the install ran with `--no-bin-links`, so no links were created (`npm rebuild` links bins afterwards); - the script names a command the package does not declare — listing `node_modules/.bin` shows exactly which commands exist; - the package that provides the command was never a dependency of this project — it only ever worked because the author had a global install. The last case is the one a global install hides: the build works on one laptop and fails on the first fresh CI runner. Declaring the tool as a devDependency is what makes the build reproducible. ## Global installs, for contrast `npm install -g` links commands into the global prefix — `{prefix}/bin` on Unix, the prefix folder itself on Windows — and that folder has to be on your shell's `PATH`. A global install is **one version per machine**, recorded in no project's `package.json` or lockfile. That makes it fine for personal tools and a poor fit for anything a project's build depends on: two projects that need different majors of the same tool cannot share one global copy, while each project's `node_modules/.bin` can hold its own.
- Why do teams keep build tools as project devDependencies instead of global installs?A devDependency is recorded in `package.json` and the lockfile, so every clone and every CI run gets the same version after `npm install` or `npm ci`, and two projects can use different majors side by side. A global install is one unrecorded version per machine, so builds silently depend on whatever each laptop happens to have.
- If an install ran with `--no-bin-links`, how do you get the commands into `node_modules/.bin` later?Run `npm rebuild` without that flag. Besides re-running install lifecycle scripts, it links bins when bin links are enabled, which is the documented way to choose later which packages to build and link after installing with `--ignore-scripts` and `--no-bin-links`.
- Which directory does an npm script run in when you call `npm run build` from a subfolder?The package root, always. npm runs scripts from the folder that holds `package.json`, regardless of your current directory, and exposes the directory you started in as `INIT_CWD` for scripts that need to act relative to it.
- npm run finds vite because npm installs build tools globally
- Scripts only work if they spell out the full node_modules/.bin path
- Typing vite in a terminal behaves exactly like calling it inside an npm script
- devDependencies never get linked into node_modules/.bin
- npx always downloads a fresh copy even when the package is installed locally