npm scripts: run, pre and post
A script is a name for a command line, stored in the scripts table of package.json. npm reads that table, and npm run takes a name from it, finds the command and runs it through a shell with node_modules/.bin in front of the PATH, which is why a tool installed in the project runs by its bare name and not by a path.
The lesson takes one small project with a build that has a step before and a step after, passes arguments into a script, and ends with the exit status of a script that fails and of a name that does not exist. Those three details are what makes a script table usable inside a pipeline.
npm run and the script table
The table has six entries. build is surrounded by prebuild and postbuild, and npm runs those two on its own: a script named pre<name> runs before name and post<name> runs after it, without being asked.
The file package.json:
vi package.json
{
"name": "scripts-course",
"version": "1.0.0",
"type": "commonjs",
"scripts": {
"prebuild": "node prebuild.js",
"build": "node build.js",
"postbuild": "node postbuild.js",
"echo": "node echo.js",
"start": "node index.js",
"fail": "node fail.js"
}
}
The three build programs print the step they are on, so the order is visible in the output and not only in the documentation.
The file prebuild.js:
console.log('prebuild: the old output is removed');
The file build.js:
console.log('build: three files written to dist');
The file postbuild.js:
console.log('postbuild: dist is ready');
npm run prints a header with the name and the version of the package before the output of the script, and --silent removes it. The block below is the output of the three programs and nothing else.
npm run --silent build
prebuild: the old output is removed
build: three files written to dist
postbuild: dist is ready
Three programs ran for one word on the command line, and the middle one is the script that was asked for. The pair is not a convention of this course: npm documents it as the lifecycle of every script and runs it for npm start and npm test as well, which is why an install hook is called postinstall.
The names that skip run
Four names are shortcuts: start, test, stop and restart run without the word run in front of them. npm start is npm run start, and it exists because every project used to have the same script.
The file index.js:
console.log('start: the program is running');
npm start --silent
start: the program is running
The shorthand takes the same flags in the same place, so --silent works after the name. A package with no start script answers with the missing script error of the last section, and not with a default command.
Arguments after two dashes
Everything after -- belongs to the script and everything before it belongs to npm. Without the separator npm reads the flags of the script as its own, which is the most common surprise of the table: a flag that vanishes instead of reaching the program.
The file echo.js:
console.log('the script was called with:', JSON.stringify(process.argv.slice(2)));
npm run --silent echo -- --name=notes one
the script was called with: ["--name=notes","one"]
The program received both arguments, in the order they were written. Drop the two dashes and npm takes the flag for itself, so the program sees only the plain word and nothing tells the reader where the flag went.
npm run --silent echo --name=notes one
the script was called with: ["one"]
process.argv.slice(2) is the argument list of any program, and the lesson on process covers the first two entries. A script that forwards its own arguments to another tool, which is what eslint --fix through a script looks like, is the usual reason to need the separator.
The exit status and a missing script
npm returns the exit status of the script, so a failing script fails the whole command. That single rule is what lets a pipeline stop at the first broken step, and the status is the only thing a caller has to read.
The file fail.js:
console.log('fail: the check found a problem');
process.exitCode = 1;
npm run --silent fail
echo "the exit status: $?"
fail: the check found a problem
the exit status: 1
A name that is not in the table fails before anything runs, and the message is npm's own: it names the lacking script and points at the command that lists the rest. npm writes one more line after the block, with the path of its log file, which is left out here.
npm run nosuch
npm error Missing script: "nosuch"
npm error
npm error To see a list of scripts, run:
npm error npm run
npm run with no name prints the table itself, with the lifecycle scripts first, and exits with 0. The lesson that puts the checks in one script builds on the status: three commands joined by && stop at the first one that fails.
Exercises
- Add a prestart script and run npm start. Which line comes first, and does the shortcut run the pair?
- Write a script that prints process.env.PATH and find the first entry. Which folder does npm put in front of the path, and which command in it can the script now call by name?
- Pass a flag with a value after --, once with the separator and once without it. Which arguments does the program see in each case?
- Make a script exit with 3 and print $? after npm run. Which number comes back, and what does the shell see?
- Run npm run with no name. Which of the six scripts are listed as lifecycle scripts, and why is that word there?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which scripts does
npm run buildrun when the table hasprebuild,buildandpostbuild?Answer
prebuild, then build, then postbuild
The pre and post names are the lifecycle around the script that was asked for.
-
What does this program print?
const scripts = { build: "node build.js", prebuild: "node pre.js" }; console.log(Object.keys(scripts).join(","));Answer
build,prebuild
The keys keep the order of the object, and build was written first.
-
What does npm put in front of the PATH for a script?
Answer
node_modules/.bin of the project
That folder holds one link per installed tool, so a script names the tool and not its file.
-
What does this program print?
const scripts = { build: "node build.js" }; console.log(scripts["build"]);Answer
node build.js
A script is a string, and the lookup returns the string that the name points at.
-
What does the
--innpm run echo -- --name=notesseparate?Answer
The arguments of npm from the arguments of the script
Everything after the separator reaches the program, and everything before it is read by npm.
-
What does this program print?
const argv = ["node", "echo.js", "--name=notes", "one"]; console.log(argv.slice(2).join(" "));Answer
--name=notes one
The first two entries are the runtime and the file, and the arguments start at index two.
-
A script sets
process.exitCode = 1. What doesnpm runreturn?Answer
1, the status of the script
npm passes the status through, which is what stops a chain of commands at the failing step.
-
What does
npm startdo?Answer
It runs the start script, like
npm run startstart is one of the four shortcut names, and the script decides what it does.
-
What does this program print?
const order = ["prebuild", "build", "postbuild"]; console.log(order.indexOf("build"));Answer
1
The three names are at the indexes 0, 1 and 2, and build is the second.
-
What does
npm runwith no script name print?Answer
The list of scripts of the package
The command lists the lifecycle scripts first and the rest of the table after them.
The programs and commands on this page were run with Node.js 24.22.1 and npm 11.12.1, and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev