concurrently

concurrently is a cross-platform CLI and Node.js library that runs multiple shell commands at the same time from a single terminal session, instead of juggling command1 & command2 shell syntax or several open terminal tabs. It’s most commonly dropped into an npm scripts block to run a dev server, a CSS watcher, and a test runner together, prefixing each command’s output with a distinct name and color so interleaved logs stay readable.

Beyond simple parallel execution, it adds process-lifecycle controls that raw shell backgrounding doesn’t offer: killing all sibling processes when one exits (or fails), restart-on-crash with configurable retry counts, wildcard expansion for npm:-prefixed script names, and a choice of success conditions (first, last, or all commands must exit cleanly) so CI pipelines can fail correctly. It works identically on Windows, macOS, and Linux.

What You Get

• A concurrently (aliased conc) CLI that accepts any number of quoted shell commands and runs them in parallel from one terminal
• Automatic, color-coded prefixing of each command’s stdout/stderr by name, index, PID, or a custom template
• --kill-others / --kill-others-on-fail to tear down all sibling processes when one exits or fails, avoiding orphaned watchers
• npm:script-name and wildcard (npm:watch-*) expansion to run several package.json scripts without repeating boilerplate
• Configurable --success conditions (first, last, all, or by command name/index) so the process exit code reflects the outcome CI or scripts care about
• A programmatic concurrently(commands, options) JS/TS API with the same feature set as the CLI, returning spawned Command objects and RxJS observables for output/state/close events
• --restart-tries and --restart-after for automatically respawning a command that crashes

Common Use Cases

• Running a frontend dev server, a backend API server, and a CSS/asset watcher together with one npm run dev command
• Wiring npm:build-* wildcard scripts so a monorepo’s per-package build scripts all run in parallel from the root
• CI pipelines that need to start a server and then run tests against it, killing the server once the test command exits
• Local development setups that watch and rebuild multiple targets (JS, CSS, docs) simultaneously with clearly separated, colorized logs

Under The Hood

Architecture - The core concurrently() function in lib/concurrently.ts runs each command string through a small pipeline of CommandParser implementations (ExpandShortcut, ExpandWildcard, and, when additionalArguments is set, ExpandArguments) before wrapping each resolved command in a Command instance (lib/command.ts) paired with spawn options from getSpawnOpts (lib/spawn.ts). Cross-cutting behaviors — killing others on exit, restarting crashed processes, handling stdin, logging timings, tearing down on signals — are implemented as independent FlowControllers under lib/flow-control/ and threaded through the command list via a single reduce call, so each concern (kill-others, restart-process, log-output, teardown, etc.) stays in its own file and is unit-testable in isolation. A CompletionListener subscribes to each command’s close observable and resolves/rejects the overall result promise according to the configured successCondition, while a semaphore-like maybeRunMore loop enforces maxProcesses by only starting a new command when a running one closes.

Tech Stack - Written in strict TypeScript ("strict": true in tsconfig.json) targeting Node 22+, compiled with tsc --build. Process orchestration relies on RxJS 7 observables (stdout, stderr, close, stateChange per command) rather than plain EventEmitters, chalk for prefix coloring, yargs for CLI argument parsing (bin/index.ts), tree-kill to reliably terminate process trees across platforms, and shell-quote/supports-color for command parsing and terminal capability detection. The repo is a pnpm workspace with Husky + lint-staged wiring pre-commit formatting and linting.

Code Quality - The lib/ and bin/ directories carry 29 .spec.ts files sitting alongside their implementation files (e.g. command.spec.ts, spawn.spec.ts, each flow-control/*.spec.ts), run through Vitest with a separate smoke test project (tests/smoke-tests.spec.ts) that exercises the built CLI end-to-end, plus dedicated ESM/CJS import tests (tests/esm, tests/cjs-require). ESLint runs @eslint/js + typescript-eslint recommended configs plus eslint-plugin-simple-import-sort, eslint-plugin-prettier, and a Vitest-specific plugin, enforced via a Husky pre-commit hook, and Coveralls tracks coverage in CI. Naming is consistent and interfaces (CommandInfo, ConcurrentlyOptions, CloseEvent) are documented with JSDoc directly in the type definitions.

API Design - The public surface is intentionally small: a single concurrently(commands, options) function returning { result, commands }, mirrored almost 1:1 by CLI flags (--kill-others, --restart-tries, --success, etc.) documented inline via yargs .describe() calls and expanded further in docs/cli. Commands can be passed as plain strings or { command, name, prefixColor, env, cwd, ipc } objects, keeping the common case (a list of strings) friction-free while still allowing per-command overrides. Getting started requires no configuration beyond installing and calling the CLI with quoted commands, and the README documents every option’s default and interaction with others (e.g. how raw overrides prefixing).