36

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?

ruakh
  • 175,680
  • 26
  • 273
  • 307
Elangovan
  • 3,469
  • 4
  • 31
  • 38
  • The [documentation](https://docs.npmjs.com/cli/run-script) says: *This is the plumbing command called by npm link and npm install. It should generally be called during installation, but if you need to run it directly, run: `npm run-script build`* – Datz Aug 06 '19 at 15:12
  • @Datz That documentation was erroneous. See [this PR](https://github.com/npm/cli/pull/5192) and [this issue](https://github.com/npm/cli/issues/5185). – Colm Bhandal Jul 19 '22 at 20:02

4 Answers4

17

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.

IlIIlllIIIlIIlllIlIllIIIlIlI
  • 757
  • 5
  • 18
  • 18
    I suspect that this answer was never accepted because it is just as confusing to *NPM Noobies* as the documentation. I came here because I did not understand when to use `npm run-script` and when to use `npm build` in the documentation. This answer gets me no closer to understanding. –  Nov 12 '20 at 22:08
  • Documentation link broken – Colm Bhandal Jul 18 '22 at 14:56
14

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>

Jimmy
  • 2,805
  • 6
  • 43
  • 57
Jeremy Foster
  • 4,673
  • 3
  • 30
  • 49
  • `npm build == npm run-script build`. I'm not sure what you mean by `==` but based on my interpretation of `==` that is incorrect. What do you mean by it? – Colm Bhandal Jul 19 '22 at 19:55
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:

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.

Colm Bhandal
  • 3,343
  • 2
  • 18
  • 29
  • 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'. – vikas pachisia Aug 28 '22 at 14:45
  • @vikaspachisia Are you proposing an alternative answer, or do you have criticism aimed at this answer? If the former, then please post your own answer. If the latter, then be more specific with your criticism. Thanks. – Colm Bhandal Aug 29 '22 at 14:42
  • It was not criticism for sure. I was trying to add on to the answer provided by you. But if you think this should not be an add on, then I have no issues in posting it as another answer (different perspective) but not alternate to what was answered earlier. – vikas pachisia Jan 10 '23 at 10:55
  • Constructive criticism is welcome; adding your own answer is totally within the guidelines of this site. – Colm Bhandal Jan 11 '23 at 11:25
  • I found this answer more suitable for beginner like me who try to understand between npm build and npm run-script. – Sahil M. Feb 21 '23 at 10:42
0

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'.

vikas pachisia
  • 553
  • 5
  • 8