Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

You typed npm build and your package.json build script never ran

Errornpm build runs, but the build script in package.json does not execute

Short answer

npm has no command that runs your build script when you type npm build. Scripts you define yourself, such as build, run only through npm run build. Check that the script exists in the package.json of the folder you are in, and put a double dash before any flag you want the script to receive.

  • Applies to npm 10, npm 11, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the scripts npm can see in the current folder. If build is not in the list, you are in the wrong folder or the script is not defined.

    npm run
  2. 2Match what you see, then jump to its fix

    1. 1You typed npm build (or npm build:prod) and the build script's own output never appears.The wrong command: build is a script name, not an npm commandFix
    2. 2npm run does not list build among the available scripts.The script is not defined in this package.jsonFix
    3. 3The build runs but behaves as if the flag was never given.A flag meant for the script is eaten by npmFix

What does the error look like?

  • npm build runs, but the build script in package.json does not execute
  • no build output folder appears after npm build
  • npm run build ignores the flag I added: --mode production

Cause 1 of 3

The wrong command: build is a script name, not an npm command

1Check

The npm scripts documentation says build is not one of the special lifecycle scripts (prepare, prepublish, prepack and so on). It is an arbitrary name, and arbitrary names run through npm run.

grep -n '"build"' package.json

2Fix

Run the script with npm run. The same rule holds for any custom script name.

npm run build

3Verify

The command prints the script line it runs, then the output of your bundler or compiler.

npm run build

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The script is not defined in this package.json

1Check

npm run without a name lists the scripts of the package.json it finds. In a monorepo the root file often has no build script; it lives in a sub-package.

pwd
npm run

2Fix

Add the script to the file you are in, or change into the folder that has it. A script that is optional in some packages can be run with --if-present so npm does not exit with an error where it is missing.

# package.json
"scripts": {
  "build": "tsc -p tsconfig.json"
}

# or, to skip packages that have no build script
npm run build --if-present

3Verify

The script now shows up in the list.

npm run

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

A flag meant for the script is eaten by npm

1Check

npm parses any option that starts with a dash before it reaches your script. Only what follows a bare double dash is passed on.

cat package.json | grep -n '"build"'

2Fix

Put -- between the script name and its flags. The arguments go to the named script only, not to its pre and post scripts.

npm run build -- --mode production

3Verify

The script receives the flag; confirm by printing process.argv in a small script or by the changed output.

npm run build -- --help

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Use npm run <name> for every script you define; keep the bare form (npm test, npm start) for the ones npm documents.
  • Run npm run with no name after cloning a repo to see what it offers.
  • In a monorepo, say in the README which folder each build is run from.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.