bun-tasks

bun-tasks is a powerful parallel task runner designed for the Bun runtime, taking inspiration from the popular tool concurrently. This utility streamlines the management of multiple tasks by enabling their concurrent execution, significantly enhancing productivity in development environments.

Key Features

• Efficiency: Execute multiple commands simultaneously using ::: as a command separator, allowing for more efficient use of resources.
• Environment Variable Management: Supports merging global and per-command environment variables, ensuring flexibility and convenience.
• Script Expansion: Automatically expands package scripts to bun run <script> when required, simplifying command execution.

Usage Example

To quickly get started, you can register scripts in your package.json, which can fan out to various commands as shown below:

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

In this example, commands such as api and docs are referenced, allowing for seamless execution:

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

Command Syntax

The bun-tasks CLI interprets commands in various formats:

• scriptName expands to bun run scriptName
• Directly includes commands with bun run <task>
• Executes any other executables directly, such as node tools/build.js

Environment Variables

Global key/value pairs can be applied to every command using the --args or -a flags. These can also be defined at the command level, with duplicates resolved in favor of the command-specific values:

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

CLI Flags

The CLI provides several useful flags for enhanced usability:

• --help, -h to display usage information.
• --version, -v to show the current version from package.json.
• --args, -a for attaching key/value pairs.
• --raw, -r to preserve the child process's native output, beneficial for displaying progress.

Programmatic Usage

For those interested in custom orchestration, the CLI can be imported and executed programmatically:

import { BunTasksCLI } from "bun-tasks";

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

This approach provides flexibility and fine control over task management, ensuring that nothing runs automatically upon import.

Development Setup

For contributors, the package provides basic commands for testing and coverage reporting:

bun install
bun test --coverage

For Windows users, note that Bun coverage reporting is still experimental, and the --coverage flag can be omitted if issues arise.