bun-workspaces
A CLI and API on top of native Bun workspaces

v1.0.0-alpha.21

What's New

Notable recent updates 📦

Installation#

You can install the package in your project or simply use bunx bun-workspaces to immediately use the latest version of the CLI. Installation is required to use the API.

# Install to use the API and/or lock your CLI version for your project
bun add --dev bun-workspaces

# Start using the CLI with or without the installation step
bunx bun-workspaces --help

If you use the CLI frequently, you might consider using a shell alias.

# Add this to .bashrc, .zshrc, or similar 
# to make it available by default in your shell
alias bw="bunx bun-workspaces"

Examples in these docs will use the alias bw for bunx bun-workspaces for brevity.

Quick Start#

CLI#

See the full CLI documentation or continue for some quick examples.

# List all workspaces in your project
bw list-workspaces

# ls is an alias for list-workspaces
bw ls --json --pretty # Output as formatted JSON

# Run the lint script for all workspaces
# that have it in their "scripts" field
bw run-script lint

# run is an alias for run-script
bw run lint my-workspace # Run for a single workspace
bw run lint my-workspace-a my-workspace-b # Run for multiple workspaces
bw run lint "my-workspace-*" # Run for matching workspace names
bw run lint --parallel # Run at the same time
bw run lint --args="--my-appended-args" # Add args to each script call
bw run lint --args="--my-arg=<workspaceName>" # Use the workspace name in args

# Show usage (you can pass --help to any command)
bw help
bw --help

# Pass --cwd to any command
bw --cwd=/path/to/your/project ls
bw --cwd=/path/to/your/project run my-script

# Pass --log-level to any command (debug, info, warn, error, or silent)
bw --log-level=silent run my-script

API#

See the full API documentation or continue for some quick examples.

import { createFileSystemProject } from "bun-workspaces";

// A Project contains the core functionality of bun-workspaces.
const project = createFileSystemProject({
  rootDirectory: "path/to/your/project",
});

// A Workspace that matches the name or alias "my-workspace"
const myWorkspace = project.findWorkspaceByNameOrAlias("my-workspace");

// Array of workspaces whose names match the wildcard pattern
const wildcardWorkspaces = project.findWorkspacesByPattern("my-workspace-*");

// Array of workspaces that have "my-script" in their package.json "scripts"
const workspacesWithScript = project.listWorkspacesWithScript("my-script");

// Run a script in a workspace
const runSingleScript = async () => {
  const { output, exit } = project.runWorkspaceScript({
    workspaceNameOrAlias: "my-workspace",
    script: "my-script",
    args: "--my --appended --args", // optional, arguments to add to the command
  });
  
  // Get a stream of the script subprocess's output
  for await (const { text, textNoAnsi, streamName } of output) {
    console.log(text); // The output chunk's content (string)
    console.log(textNoAnsi); // Text with ANSI codes sanitized (string)
    console.log(streamName); // The output stream, "stdout" or "stderr"
  }
  
  // Get data about the script execution after it exits
  const exitResult = await exit;
  
  console.log(exitResult.exitCode); // The exit code (number)
  console.log(exitResult.signal); // The exit signal (string), or null
  console.log(exitResult.success); // true if exit code was 0
  console.log(exitResult.startTimeISO); // Start time (string)
  console.log(exitResult.endTimeISO); // End time (string)
  console.log(exitResult.durationMs); // Duration in milliseconds (number)
  console.log(exitResult.metadata.workspace); // The target workspace (Workspace)
}

// Run a script in all workspaces that have it in their package.json "scripts" field
const runManyScripts = async () => {
  const { output, summary } = project.runScriptAcrossWorkspaces({
    workspacePatterns: ["*"], // this will run in all workspaces that have my-script
    script: "my-script", // the package.json "scripts" field name to run
    args: "--my --appended --args", // optional, arguments to add to the command
    parallel: true, // optional, run the scripts in parallel
  });
  
  // Get a stream of script output
  for await (const { outputChunk, scriptMetadata } of output) {
    console.log(outputChunk.text); // the output chunk's content (string)
    console.log(outputChunk.textNoAnsi); // text with ANSI codes sanitized (string)
    console.log(outputChunk.streamName); // "stdout" or "stderr"
  
    // The metadata can distinguish which workspace script 
    // the current output chunk came from
    console.log(scriptMetadata.workspace); // Workspace object
  }
  
  // Get final summary data and script exit details after all scripts have completed
  const summaryResult = await summary;
  
  console.log(summaryResult.totalCount); // Total number of scripts
  console.log(summaryResult.allSuccess); // true if all scripts succeeded
  console.log(summaryResult.successCount); // Number of scripts that succeeded
  console.log(summaryResult.failureCount); // Number of scripts that failed
  console.log(summaryResult.startTimeISO); // Start time (string)
  console.log(summaryResult.endTimeISO); // End time (string)
  console.log(summaryResult.durationMs); // Total duration in milliseconds (number)
  
  // The exit details of each workspace script
  for (const exitResult of summaryResult.scriptResults) {
    console.log(exitResult.exitCode); // The exit code (number)
    console.log(exitResult.signal); // The exit signal (string), or null
    console.log(exitResult.success); // true if exit code was 0
    console.log(exitResult.startTimeISO); // Start time (ISO string)
    console.log(exitResult.endTimeISO); // End time (ISO string)
    console.log(exitResult.durationMs); // Duration in milliseconds (number)
    console.log(exitResult.metadata.workspace); // The target workspace (Workspace)
  }
}

bun-workspaces is independent from the Bun project and is not affiliated with or endorsed by Oven. This project aims to enhance enhance the experience of Bun for its users.