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:

``sh
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:

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

---

🛠️ CLI Usage

$3

Mix sequential and parallel groups in one command:

`sh
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)

---

$3

Shortcut for npm-run-all --sequential:

`sh
run-s clean lint build:js build:css
`

Equivalent to:

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

---

$3

Shortcut for npm-run-all --parallel:

`sh
run-p test watch serve
`

Equivalent to (Unix shells):

`sh
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 | 🔢 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 | 🔁 Retry each failed task up to times |
| --npm-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):

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

Forward arguments to scripts:

`sh
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:

`sh
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

`js
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:

`ts
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] |
| ----- | ------------- | ------- | ------- | ---------- |

[npm-run-all]: docs/npm-run-all.md
[run-s]: docs/run-s.md
[run-p]: docs/run-p.md
[node api]: docs/node-api.md

---

📄 License

MIT © 2025 Alec Mestroni