npm-run-all-next

A modern, drop-in task runner for npm, pnpm, and yarn.

It lets you run multiple npm scripts in series or in parallel, with smart features for real-world CI/CD and monorepos:

• robust retries for flaky tasks
• intelligent parallelization / load balancing
• human-friendly summary tables
• cross-platform behavior (Windows / macOS / Linux)
• usable both as CLI (run-s, run-p, npm-run-all) and as a Node API

Why NEXT? 🚀

npm-run-all-next is a modern evolution of npm-run-all, built for today’s workflows:

• 🔁 --retries
  Automatically retry flaky tasks without rewriting scripts.

• ⚖️ --balancer
  Parallel tasks are scheduled using historical runtime data, so long-running tasks are started earlier and total build time goes down.

• 📊 --print-summary-table
  Get a final report with exit code, retries, and duration for each task.

• 📂 --tasks-file
  Load task lists from an external file (JSON/JS), so your package.json doesn’t become unreadable.

• 🧵 Familiar commands
  run-s, run-p, and npm-run-all are included and cross-platform.

• 🧪 First-class Node API
  Run tasks programmatically with runTasks([...]).

This tool is designed for CI pipelines, monorepos, and multi-step local dev workflows — not just simple "run two scripts at once."

---

📖 Table of Contents

• 📦 Installation
• 🛠️ CLI Usage
  • ⚙️ npm-run-all-next
  • ▶️ run-s (sequential)
  • 🔀 run-p (parallel)
  • 🛡️ Common Options
• 🔍 Patterns & Placeholders
• 📦 Node API
• 🤝 Contributing
• 📄 License

---

📦 Installation

Install as a development dependency:

npm install --save-dev npm-run-all-next

All commands are exposed in node_modules/.bin:

• ✔️ npm-run-all-next
• ✔️ run-s
• ✔️ run-p

You can also add them to your package.json scripts:

{
  "scripts": {
    "build:js": "…",
    "build:css": "…",
    "lint": "…",
    "clean": "…",
    "test": "…",
    "serial": "run-s clean lint build:*",
    "parallel": "run-p lint test clean"
  }
}

---

🛠️ CLI Usage

⚙️ npm-run-all-next

Mix sequential and parallel groups in one command:

npm-run-all clean lint \
  --parallel build:* \
  --sequential test:* \
  --parallel deploy

This runs:

1. clean then lint (serial)
2. build:* tasks (parallel)
3. test:* tasks (serial)
4. deploy (parallel with a single task)

---

▶️ run-s (sequential)

Shortcut for npm-run-all --sequential:

run-s clean lint build:js build:css

Equivalent to:

npm run clean && npm run lint && npm run build:js && npm run build:css

---

🔀 run-p (parallel)

Shortcut for npm-run-all --parallel:

run-p test watch serve

Equivalent to (Unix shells):

npm run test & npm run watch & npm run serve

Windows cmd.exe does not group & well—use run-p instead.

---

🛡️ Common Options

Flag	Description
-a, --aggregate-output	🗃️ Buffer each task’s output and print when all finish (requires parallel)
-b, --balancer	⚖️ Balance tasks based on historical runtimes
-c, --continue-on-error	🚧 Don’t stop other tasks when one fails
-k, --kill-others-on-fail	💥 Kill remaining tasks on first failure (requires parallel)
-r, --race	🏁 Stop remaining tasks when one succeeds (requires parallel)
-j, --jobs <number>	🔢 Max concurrent tasks (default: unlimited; requires parallel)
-t, --print-summary-table	📊 Show a summary table of results at the end
-l, --print-label	🏷️ Prefix each output line with the task label
-n, --print-name	📝 Print the task name before running
--retries <count>	🔁 Retry each failed task up to <count> times
--npm-path <path>	📍 Path to a custom npm executable
--silent	🤫 Suppress all output (sets npm_config_loglevel to silent)
-h, --help	❓ Show help
-v, --version	🔖 Show version
--tasks-file	📂 Load tasks from a JSON file (overrides patterns and args)

Short flags can be combined (e.g. -crs ⇔ -c -r -s).

---

🔍 Patterns & Placeholders

Use glob-like patterns on script names (separator :, globstar ** supported):

run-p 'build:*'      # matches build:js, build:css
run-s 'test:**'      # matches test:unit, test:unit:api, etc.

Forward arguments to scripts:

run-p "start -- --port {1}" -- 8080
# 👉 expands to: npm run start -- --port 8080

Placeholders:

• {1}, {2}, … — 1st, 2nd, … argument
• {@} — all args as an array
• {*} — all args joined

---

Brace expansion

If your shell doesn’t support brace expansion, npm-run-all will expand patterns like:

run-p build:{a,b,c} # ↔> run-p build:a build:b build:c

…so you can target multiple scripts in one pattern.

📦 Node API

const { runTasks } = require("npm-run-all-next")

runTasks(["clean", "lint", "build:*"], {
  parallel: true,
  retries: 2,
  killOthersOnFail: true,
  printSummaryTable: true,
})
  .then((results) => {
    // results: [{ name: 'clean', code: 0 }, …]
    console.log("✅ Done:", results)
  })
  .catch((err) => {
    console.error("❌ Failed:", err.results)
  })

Options mirror CLI flags:

interface RunOptions {
  parallel?: boolean
  aggregateOutput?: boolean
  balancer?: boolean
  continueOnError?: boolean
  killOthersOnFail?: boolean
  race?: boolean
  jobs?: number
  retries?: number
  printSummaryTable?: boolean
  printLabel?: boolean
  printName?: boolean
  npmPath?: string
  silent?: boolean
  stdin?: Stream
  stdout?: Stream
  stderr?: Stream
  taskList?: string[]
}

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!
See CONTRIBUTING.md for guidelines.

---

---

📚 Main docs

index	npm-run-all	run-s	run-p	Node API

---

📄 License

MIT © 2025 Alec Mestroni