npm-run-all

Common errors

• MaxListenersExceededWarning

  cause Running a large number of tasks in parallel could trigger Node.js's default `MaxListenersExceededWarning` due to too many event listeners being attached.
  fix Upgrade to `npm-run-all@4.1.0` or newer, which includes a fix for this issue. Alternatively, consider using the `--max-parallel` option to limit the number of concurrently running tasks.

• Error: The script name which starts with '!' makes `npm-run-all` confusing.

  cause A bug in earlier versions of `npm-run-all` caused issues when npm script names started with the '!' character.
  fix Rename your npm scripts to avoid starting with '!'. Upgrade to `npm-run-all@4.1.3` or newer, which contains a fix for this specific problem.

• The --aggregate-output option does not work if child tasks print large output.

  cause In versions prior to 4.1.2, the `--aggregate-output` option could fail to function correctly if the child tasks generated a very large amount of output, or when used directly with the `npm-run-all` command itself rather than `run-s`/`run-p`.
  fix Update to `npm-run-all@4.1.2` or a later version to ensure the `--aggregate-output` option handles large outputs and works consistently across all commands.

• Assertion check about --race option failed when there is a mix of --parallel and --serial.

  cause A bug in `npm-run-all@4.0.0` and `4.0.1` caused an assertion check for the `--race` option to fail if it was used in a command that also mixed `--parallel` and `--serial` options.
  fix Upgrade to `npm-run-all@4.0.2` or a newer version to resolve the incorrect assertion failure with the `--race` option.

Warnings

• breaking Version 4.0.0 dropped support for Node.js versions 0.10 and 0.12. Ensure your Node.js environment is Node >=4.
  Fix: Upgrade your Node.js runtime to version 4 or higher. For modern development, Node.js 14+ is recommended.
• breaking In v4.0.0, the mechanism for finding the `npm` executable changed. It now prioritizes the `NPM_EXECPATH` environment variable, which `npm run-script` sets. If `NPM_EXECPATH` is not defined, it falls back to the old method of using `npm` from the `PATH`. This might affect environments where `npm-run-all` is invoked outside of a standard `npm run` context or with specific `npm` versions.
  Fix: Verify that your `NPM_EXECPATH` environment variable is correctly set if you rely on a specific `npm` path. Otherwise, ensure `npm` is available in your system's `PATH`.
• gotcha The `--aggregate-output` option, introduced in v4.1.0, buffers output until a task completes, preventing interleaved logs in parallel mode. However, it should NOT be used for long-running or never-finishing tasks (e.g., web servers, file watchers), as their output will never be displayed.
  Fix: Reserve `--aggregate-output` for short-lived tasks. For long-running processes, omit this option to allow real-time output streaming.
• gotcha Script names beginning with `!` could cause `npm-run-all` to behave unexpectedly due to misinterpretation.
  Fix: Avoid using `!` as the starting character for your npm script names. Upgrade to version 4.1.3 or higher to benefit from the fix.
• gotcha The `--race` option, intended to terminate all tasks once one finishes with a zero exit code (success), had a bug that caused unintentional failures when mixed with `--parallel` and `--serial` directives.
  Fix: Ensure you are using `npm-run-all@4.0.2` or newer to correctly use the `--race` option in combination with other execution modes.

Install

• npm install npm-run-all npm
• yarn add npm-run-all yarn
• pnpm add npm-run-all pnpm

Imports

• runAll
  wrong:

  import npmRunAll from 'npm-run-all';

  correct:

  import { runAll } from 'npm-run-all';

  The primary programmatic API is exported as named functions, not a default export. The main function is `runAll`.
• runParallel
  wrong:

  import { parallel } from 'npm-run-all';

  correct:

  import { runParallel } from 'npm-run-all';

  For directly invoking parallel script execution from Node.js, use `runParallel`. `parallel` is a CLI option shorthand.
• npm-run-all (CommonJS)
  wrong:

  const runAll = require('npm-run-all').runAll;

  correct:

  const { runAll, runSequential, runParallel } = require('npm-run-all');

  The `require('npm-run-all')` call returns an object containing all API functions. Destructuring is common.

Quickstart

This quickstart demonstrates how to define npm scripts in `package.json` and execute them using `npm-run-all`, `run-s` (sequential), and `run-p` (parallel) via `npx` for both simple and complex task flows.

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "clean": "echo \"Cleaning build artifacts...\"",
    "lint": "echo \"Running linter...\"",
    "build:css": "echo \"Compiling CSS...\"",
    "build:js": "echo \"Bundling JavaScript...\"",
    "deploy": "echo \"Deploying application...\""
  },
  "devDependencies": {
    "npm-run-all": "^4.1.5"
  }
}

// To install, run: npm install npm-run-all --save-dev

// 1. Run 'clean' then all 'build:*' scripts sequentially using 'run-s' shorthand.
//    Output for each script will appear in order.
// npx run-s clean 'build:*'

// 2. Run 'lint', 'build:css', and 'build:js' in parallel using 'run-p' shorthand.
//    Outputs might be interleaved as scripts complete.
// npx run-p lint build:css build:js

// 3. Combine sequential and parallel execution using 'npm-run-all':
//    First 'clean', then 'lint' and 'build:css' in parallel, then 'deploy' sequentially.
// npx npm-run-all clean --parallel lint build:css --serial deploy