Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Scripts and Workspaces

npm Scripts

Learn how the scripts field works, how npm run, yarn and pnpm run scripts, the special start and test commands, passing arguments, chaining commands and how node_modules/.bin is added to PATH.

The scripts field turns long, hard-to-remember commands into short names. Instead of telling every teammate "run eslint src --ext .js --max-warnings 0", you give them npm run lint. Scripts are also the standard interface between your project and tools such as CI servers and hosting platforms, which know to run npm test and npm run build.

Defining and running scripts

JSON
{
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js",
    "build": "tsc --project tsconfig.json",
    "lint": "eslint src",
    "test": "node --test"
  }
}

Run them like this (read-only commands):

Terminal
npm run build        # any script
npm start            # shortcut for: npm run start
npm test             # shortcut for: npm run test   (also: npm t)
yarn build           # Yarn: the "run" is optional
pnpm build           # pnpm: also optional unless the name clashes with a built-in
npm run              # with no name: list all scripts

start and test get dedicated shortcuts, and npm stop and npm restart exist too. Every other name needs npm run.

If you do not define start, npm runs node server.js when a server.js file exists. Define it explicitly so nobody has to guess.

What is a script, really?

A script is a string handed to your system shell (sh on macOS and Linux, cmd.exe on Windows by default). Anything you can type in a terminal works: pipes, &&, environment variables. Because the shell differs per platform, advanced syntax can break across systems; see Environment Variables and Cross-Platform Scripts.

npm also puts node_modules/.bin at the front of PATH while the script runs. That is why "lint": "eslint src" works even though eslint is not installed globally: it finds the project's copy.

Node.js Run a script string the way npm does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The runner's sandbox allows spawning a shell, but on your machine remember that echo, rm and && behave slightly differently on Windows.

Passing arguments

Anything after -- is passed to the script's command, not to npm:

Terminal
npm run test -- --watch      # runs: node --test --watch   (npm 7+: needed for flags)
npm run lint -- --fix
yarn test --watch            # Yarn and pnpm pass the extra arguments straight through
pnpm test --watch

Inside a Node script you read those with process.argv.slice(2).

Node.js Separating flags from values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Running several scripts

Chain with the shell: && runs the next command only if the previous succeeded, ; runs regardless (Unix), and || runs the next on failure.

JSON
{
  "scripts": {
    "check": "npm run lint && npm run test",
    "build": "npm run clean && tsc",
    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\""
  }
}

Running scripts in parallel is not built into npm. Use the & operator on Unix (fragile), or the tools npm-run-all2 (run-p, run-s) and concurrently. npm 7+ can run a script in every workspace (npm run test --workspaces), and pnpm has pnpm -r run test and --parallel.

Exit codes drive everything

A script succeeds when its command exits with code 0 and fails on any other code. CI uses that to decide whether a build is green. So "test": "echo \"no tests\" && exit 1" (the default that npm init writes) deliberately fails.

Node.js Exit codes and && chains

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Useful built-in variables

Inside any script npm sets variables you can read from the environment: npm_package_name, npm_package_version, npm_lifecycle_event (the script name) and npm_config_* values. Use process.env.npm_package_version in a Node script to print the package version.

Naming conventions

Short, lowercase names with a colon namespace for variants are common: build, build:prod, test:unit, test:e2e, lint:fix. Keep scripts one-liners; move longer logic into a file ("release": "node scripts/release.mjs"), which is easier to read and works across platforms.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you pass a flag through npm run to the underlying command?

    The -- separator tells npm to forward the rest to the script.
  2. 2. Why can a script call eslint without a global install?

    npm prepends node_modules/.bin to PATH.
  3. 3. Which script names can be run without the word run in npm?

    npm start, npm test, npm stop and npm restart are shortcuts.
  4. 4. What does a script's exit code 0 mean?

    Zero means success; any other code is a failure.

Summary

  • scripts maps names to shell commands; run them with npm run <name>, yarn <name> or pnpm <name>.
  • start and test have shortcuts.
  • node_modules/.bin is on PATH during scripts, so local tools just work.
  • Extra arguments go after -- (npm).
  • Chain with &&; exit codes decide success; move complex logic into files.

Next: Lifecycle Scripts and Hooks