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.
// Below defaults to process.cwd() for the project root directory
// Pass { rootDirectory: "path/to/your/project" } to use a different root directory
const project = createFileSystemProject();

// 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) {
    // outputChunk.raw // The raw output content (Uint8Array)
    // outputChunk.decode() // The output chunk's content (string)
    // outputChunk.decode({ stripAnsi: true }) // Text with ANSI codes sanitized (string)
    // outputChunk.streamName // The output stream, "stdout" or "stderr"
  }
  
  // Get data about the script execution after it exits
  const exitResult = await exit;
  
  // exitResult.exitCode // The exit code (number)
  // exitResult.signal // The exit signal (string), or null
  // exitResult.success // true if exit code was 0
  // exitResult.startTimeISO // Start time (string)
  // exitResult.endTimeISO // End time (string)
  // exitResult.durationMs // Duration in milliseconds (number)
  // 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({
    // Optional. This will run in all matching workspaces that have my-script
    // Accepts same values as the CLI run-script command's workspace patterns
    // When not provided, all workspaces that have the script will be used.
    workspacePatterns: ["my-workspace", "my-name-pattern-*"],
  
    // Required. The package.json "scripts" field name to run
    script: "my-script",
  
    // Optional. Arguments to add to the command
    args: "--my --appended --args",
  
    // Optional. Whether to run the scripts in parallel
    parallel: true,
  });
  
  // Get a stream of script output
  for await (const { outputChunk, scriptMetadata } of output) {
    // outputChunk.decode() // the output chunk's content (string)
    // outputChunk.decode({ stripAnsi: true }) // text with ANSI codes sanitized (string)
    // outputChunk.streamName // "stdout" or "stderr"
  
    // The metadata can distinguish which workspace script 
    // the current output chunk came from
    // scriptMetadata.workspace // Workspace object
  }
  
  // Get final summary data and script exit details after all scripts have completed
  const summaryResult = await summary;
  
  // summaryResult.totalCount // Total number of scripts
  // summaryResult.allSuccess // true if all scripts succeeded
  // summaryResult.successCount // Number of scripts that succeeded
  // summaryResult.failureCount // Number of scripts that failed
  // summaryResult.startTimeISO // Start time (string)
  // summaryResult.endTimeISO // End time (string)
  // summaryResult.durationMs // Total duration in milliseconds (number)
  
  // The exit details of each workspace script
  for (const exitResult of summaryResult.scriptResults) {
    // exitResult.exitCode // The exit code (number)
    // exitResult.signal // The exit signal (string), or null
    // exitResult.success // true if exit code was 0
    // exitResult.startTimeISO // Start time (ISO string)
    // exitResult.endTimeISO // End time (ISO string)
    // exitResult.durationMs // Duration in milliseconds (number)
    // exitResult.metadata.workspace // The target workspace (Workspace)
  }
}