bun-tasks

bun-tasks is a parallel task runner for the Bun runtime inspired by concurrently. Make sure Bun is installed and on your PATH (run bun --version to verify) before using this library. It understands the ::: command separator, merges global and per-command environment variables, and automatically expands package scripts to bun run <script> when needed. The CLI is exposed as the binary bun-tasks; it is exported for programmatic usage but never auto-executes when imported.

Installation

bun add -D bun-tasks

Prerequisite: Bun must be available in your environment; install it from the official docs if bun --version fails.

Quick start

Register a script in package.json that fans out to multiple commands:

{
  "scripts": {
    "dev": "bun-tasks --args NODE_ENV=dev api ::: docs --args PORT=4000"
  }
}

Define the referenced scripts as usual:

{
  "scripts": {
    "api": "bun run src/api.ts",
    "docs": "bun run docs:watch",
    "dev": "bun-tasks api ::: docs"
  }
}

Command syntax

Commands are separated with :::. Each segment can take one of several forms:

• scriptName → expands to bun run scriptName using your local package.json.
• bun run <task> → forwarded as-is when you already include Bun.
• Any other executable (e.g. node tools/build.js) → executed directly by Bun.

Environment variables

• --args / -a directly after bun-tasks defines global key/value pairs applied to every command.
• --args / -a after a command defines per-command variables.
• Global and local variables are merged; duplicates prefer the command-level value.

Example:

bun-tasks -a API_URL=https://api.dev api ::: queue --args QUEUE=media -a PORT=4010

CLI flags

• --help, -h — display usage information.
• --version, -v — show the published version resolved from package.json.
• --args, -a — attach key/value pairs as described above.
• --raw, -r — bypass piping and preserve the child process's native output (useful for Parcel progress bars).

Programmatic usage

You can import the CLI class for custom orchestration:

import { BunTasksCLI } from "bun-tasks";

const cli = new BunTasksCLI();
await cli.run(["echo", "hello", ":::", "echo", "world"], {
  stdoutPrefix: (i) => `[job-${i}]`,
  mirrorStderrToStdout: true,
});

Because the package exports the class only, nothing runs automatically when the module is imported.

Development

bun install
bun test --coverage

On Windows, Bun coverage reporting is experimental; if it fails you can temporarily drop the --coverage flag while the upstream feature matures.

Acknowledgements

Portions of the codebase were authored with assistance from GPT-5-Codex.

License

MIT