API#

TypeScript#

Ensure you have @types/bun installed for accurate types. Your "lib" field in tsconfig.json should ideally include "ESNext".

Quick Start#

import { createFileSystemProject } from "bun-workspaces";

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

// 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 { outputChunk } of output) {
    console.log(outputChunk.raw); // The raw output content (Uint8Array)
    console.log(outputChunk.decode()); // The output chunk's content (string)
    console.log(outputChunk.decode({ stripAnsi: true })); // Text with ANSI codes sanitized (string)
    console.log(outputChunk.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.decode()); // the output chunk's content (string)
    console.log(outputChunk.decode({ stripAnsi: true })); // 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)
  }
}