npm-run-all

npm-run-all provides three CLI commands — npm-run-all, run-s, and run-p — for running several npm-scripts together without stitching together shell operators. Native npm only runs one script at a time, so developers historically chained commands with && (sequential) or & (parallel), but & doesn’t work in Windows’ cmd.exe, which npm run-script uses by default. npm-run-all sidesteps that by implementing its own cross-platform process orchestration, so the same script list behaves identically on Windows, macOS, and Linux.

Beyond simple chaining, it supports Glob-like patterns for matching multiple scripts by name (e.g. build:*), mixed sequential/parallel plans in one invocation, argument placeholders for forwarding CLI args into child scripts, a --continue-on-error flag, parallelism limits via --max-parallel, and a Node API for embedding the same orchestration logic directly in build scripts rather than shelling out.

What You Get

• Three CLI entry points — npm-run-all (full-featured), run-s (sequential shorthand), and run-p (parallel shorthand) — for different levels of verbosity
• Cross-platform parallel execution that works correctly on Windows’ cmd.exe, where the native & shell operator does not
• Glob-like task name matching (e.g. build:**) so one pattern can target many npm-scripts in package.json
• Mixed sequential-then-parallel execution plans in a single command, e.g. npm-run-all clean lint --parallel watch:html watch:js
• A programmatic Node API (require('npm-run-all')) for embedding the same task-running logic inside custom build scripts
• Yarn compatibility — scripts invoked via Yarn are re-run through Yarn rather than npm

Common Use Cases

• Replacing a chain of npm run clean && npm run build:css && npm run build:js with a single npm-run-all clean build:* call
• Running multiple watch processes (CSS, JS, server) together with run-p watch:* during local development
• Aborting a multi-step CI build early with --continue-on-error disabled, so a failed lint or test step stops the pipeline
• Limiting concurrency with --max-parallel when running many parallel tasks would overwhelm CI runner resources
• Forwarding CLI arguments into individual npm-scripts using {1}/{@} placeholders instead of hardcoding them per script

Under The Hood

Architecture The package is organized as a thin CLI layer (bin/npm-run-all, bin/run-s, bin/run-p) over a small library core (lib/index.js) that parses patterns, resolves them against package.json’s scripts field via lib/match-tasks.js (Glob matching through minimatch, with a TaskSet class deduping overlapping patterns), and executes them through lib/run-tasks.js and lib/run-task.js. Execution is Promise-based: run-tasks.js maintains a queue of pending tasks and a pool of in-flight promises sized by --max-parallel, spawning the next queued task as each finishes; a shared abort() path kills all in-flight child processes (including signal-to-exit-code translation per Node’s documented convention) the moment a task fails, unless --continue-on-error is set. Platform differences are isolated behind separate spawn-posix.js/spawn-win32.js modules so the parallel-abort and signal-handling logic in run-tasks.js stays platform-agnostic.

Tech Stack Plain CommonJS JavaScript (no TypeScript), targeting Node >= 4, built and published without a bundler. Runtime dependencies are narrowly scoped to the problem: cross-spawn for portable child-process spawning, minimatch for Glob-style task matching, shell-quote for safely quoting forwarded arguments, memorystream for buffering aggregated output, pidtree for locating descendant processes to kill, chalk/ansi-styles for terminal coloring, and read-pkg for locating and parsing package.json. The project is transpiled with Babel only for async/await syntax support on older Node versions, tested with Mocha plus power-assert, and measures coverage with nyc/Istanbul. CI runs on both Travis (Linux, multiple Node versions down to 4.0.0) and AppVeyor (Windows), reflecting the project’s cross-platform mandate.

Code Quality The library has a dedicated test/ directory covering parallel execution, sequential execution, mixed plans, argument placeholders, package-config overwrites, aggregated output, Yarn compatibility, print-label/print-name flags, and failure handling — run through Mocha with power-assert for expressive assertion failures and collected under nyc coverage. Source files carry consistent JSDoc annotations for every exported function and its parameters, and an ESLint config (extending a shared eslint-config-mysticatea ruleset) is enforced via a pretest hook, so lint failures block the test run. There is no static type system (plain JS, @types/node is a dev-only annotation aid), and error handling favors explicit Promise rejection with a custom NpmRunAllError type carrying structured per-task exit results rather than bare thrown strings.

What Makes It Unique The library’s specific value is not running scripts — npm can already do that — but reproducing shell-level parallel/sequential composition (&&, &) in a way that is verified to behave identically across POSIX shells and Windows’ cmd.exe, including correctly propagating signal-based exit codes and killing descendant process trees on abort (via pidtree) rather than leaving orphaned child processes behind. Its Glob-pattern task matching and {1}/{@} argument-placeholder syntax let one invocation stand in for many differently-named scripts, which is a level of expressiveness beyond what shell chaining or npm’s own run command offers natively.