What is the difference between `npm run-script build` vs `npm build`?

Question

When I run npm build, it gives this error:

npm WARN build `npm build` called with no arguments

So, what's the difference between npm run-script build and npm build?

Answer 1

In short "npm build" is a inbuilt command or as NPM creator calls it... it is a lifecycle event (predefined) where as npm run-script is a task that executes a script and hence can be defined by user differently from the lifecycle event 'build'.

Answer 2

TLDR

• npm build is an old CLI command that npm stopped exposing via their CLI after version 6 of the CLI.
• "build" is a common name chosen by developers for the user-defined script that builds their project. Developers define this in their package.json file and run with some variant of npm run-script build. If this user-defined script is not defined in package.json, the npm CLI will throw an error, just as it does when a user attempts to pass any other non-existent user-defined script to npm run-script.

Alias in Wonderland

First of all, I'll try not to go down the rabbit hole, but let me get something out of the way. At the time of writing this, run is just an alias for run-script, as are rum and urn, believe it or not. In the remainder of this answer, I will just use run-script, since it seems to be the "main" name (and not an alias) for this command. But in any of the usages below, feel free in your mind to replace run-script with run, or even rum or urn, if you are feeling quirky.

npm is a CLI

OK great, what next? Well, to avoid confusion, let's separate our concerns and first focus on the difference between npm COMMAND and npm run-script SCRIPT, in general. Here I am just using COMMAND and SCRIPT to denote some arbitrary command/script, respectively.

First, think about what npm is. It's a CLI tool. And like any other CLI tool you can think of, it has some built in commands or "verbs". For example, if we do npm ls, we can see a list of installed packages. Here ls is the COMMAND or the "verb" passed to npm.

The npm run-script command

One of the commands i.e. verbs that the npm CLI supports is run-script. This particular command will:

[run] an arbitrary command from a package's "scripts" object. If no "command" is provided, it will list the available scripts.

(source)

So for any user-defined SCRIPT you have in your package.json file, you can run it, using npm, by doing:

npm run-script SCRIPT

SCRIPT can be almost anything you like*. It's user defined. You can call a command build if you like, or you can call it billy or bilbo. Clearly, you want to call it something sensible. And that's why a lot of developers use the term build for a script which builds their project.

*There are some naming restrictions on the SCRIPT so it's not totally free-form. See here.

npm build and npm run-script build

Now that we understand npm is a CLI tool, we can finally tackle the problem of npm build. Here, we are passing build as the verb to the npm CLI. This is completely different to passing build as the name of a custom-script to run with npm run-script build.

Now, the question is, is the build command even a valid verb of the npm CLI? The answer is: it depends on the version of npm you are using:

• Version 8: There is NO build command.
• Version 7: There is NO build command.
• Version 6: There is a build command.

So npm build is only valid in version 6, and possibly earlier versions, of the npm CLI.

It's likely that NPM intentionally removed the build command from their CLI to avoid confusion. Many developers use build as the name of one of their user-defined scripts in package.json, so having another build verb in the npm CLI causes the two to be confused - hence questions like this one.

Tests

To confirm that npm build and npm run-script build are indeed different, I tested them on Docker Playground for various Node/npm versions. Here are the results:

Node Version	npm version	Result of npm build	Result of npm run-script build
node:10.0.0-slim	npm@5.6.0	No output (command apparently succeeded but didn't seem to do anything)	npm ERR! missing script: build
node:12.0.0	npm@6.9.0	No output (command apparently succeeded but didn't seem to do anything)	npm ERR! missing script: build
node:18.6.0	npm@8.13.2	Unknown command: "build" (the command failed)	npm ERR! missing script: build

Old Source of Confusion

While writing this answer, I discovered a bug in the npm version 6 docs, which, like many of us confused folk visiting this SO question, were erroneously conflating npm build with npm run-script build and adding to the confusion. I have since submitted a PR for this issue which has been merged. Hopefully it will be reflected in the npm docs soon.

---

Hopefully the links in this answer stay alive for a while, but please comment if they go stale.

Answer 3

The best answer is in this SO article.

Basically...

npm run == npm run-script

Plus, certain common tasks are aliased so that the following are true...

npm test == npm run-script test

npm build == npm run-script build

For common tasks, use...

npm start

npm build

npm test

npm restart

And for all others, use...

npm run <my-task>

Answer 4

npm run-script is a way to execute arbitrary commands specific to the project/package. Check your applicable package.json file, which will have defined what happens when you execute npm run-script build for that package. It may also include what happens when you run common commands, such as npm run-script test.

As you can see in the documentation for npm run-script, this arbitrary command can include arguments, which you need to refer to your package.json to learn more about.

npm build is not a unique command to the package, and is a native command that ships with npm, as you can see in its documentation.