workspace-utils

A powerful CLI tool designed to orchestrate scripts across monorepo workspaces with parallel execution, dependency-aware builds, and real-time log streaming.

What is workspace-utils?

workspace-utils simplifies working with monorepos by providing intelligent script orchestration across multiple packages. Whether you're using Bun, pnpm, or npm workspaces, this tool automatically detects your setup and provides a unified interface for running scripts efficiently.

Key Features

🚀 Parallel Execution by Default

Run scripts across multiple packages simultaneously with configurable concurrency limits. Perfect for tests, linting, and development workflows.

🏗️ Dependency-Aware Builds

Automatically builds packages in the correct order using topological sorting. Dependencies are always built before their dependents.

🎨 Real-time Log Streaming

Color-coded, prefixed output makes it easy to track which package is doing what. Each package gets its own color for instant identification.

🔍 Smart Package Filtering

Use glob patterns to target specific packages:

• --filter "@scope/*" - All packages in a scope
• --filter "apps/*" - All apps
• --filter "*-utils" - All utility packages

📦 Multi Package Manager Support

Works seamlessly with:

• Bun workspaces (package.json + bun.lockb)
• pnpm workspaces (pnpm-workspace.yaml + pnpm-lock.yaml)
• npm workspaces (package.json + package-lock.json)

🎯 Zero Configuration

No config files needed. Just run it in any workspace and it automatically detects your setup.

Why workspace-utils?

Before workspace-utils

# Run tests manually in each package
cd packages/utils && npm test
cd ../ui-components && npm test
cd ../api-client && npm test
cd ../../apps/web-app && npm test

# Build in correct order manually
cd packages/utils && npm run build
cd ../ui-components && npm run build  # depends on utils
cd ../api-client && npm run build     # depends on utils
cd ../../apps/web-app && npm run build # depends on ui-components & api-client

After workspace-utils

{
	"scripts": {
		"test": "wsu run test",
		"build": "wsu build",
		"dev": "wsu dev"
	}
}

# Run all tests in parallel
npm run test

# Build everything in correct dependency order
npm run build

# Start all dev servers with live logs
npm run dev

At a Glance

Quick Example

Given this monorepo structure:

my-project/
├── package.json (workspaces: ["packages/*", "apps/*"])
├── packages/
│   ├── utils/           # no dependencies
│   ├── ui-components/   # depends on utils
│   └── api-client/      # depends on utils
└── apps/
    └── web-app/         # depends on ui-components, api-client

Running npm run build (with "build": "wsu build" in package.json) will:

1. Batch 1: Build utils
2. Batch 2: Build ui-components and api-client in parallel
3. Batch 3: Build web-app

Running npm run test (with "test": "wsu run test" in package.json) will run all tests in parallel across all packages simultaneously.

Ready to Get Started?

Continue to Installation to set up workspace-utils in your project.

Installation

workspace-utils is designed to be installed as a development dependency in your project and used through package.json scripts.

Installation

Install workspace-utils as a development dependency in your monorepo root:

# npm
npm install --save-dev workspace-utils

# pnpm
pnpm add -D workspace-utils

# bun
bun add -d workspace-utils

# yarn
yarn add --dev workspace-utils

Setup Package Scripts

Add scripts to your root package.json using the wsu short command:

{
	"scripts": {
		"test": "wsu run test",
		"build": "wsu build",
		"dev": "wsu dev",
		"lint": "wsu run lint",
		"typecheck": "wsu run typecheck",
		"clean": "wsu run clean --sequential"
	}
}

Now you can run commands like:

npm run test     # Run tests across all packages
npm run build    # Build packages in dependency order
npm run dev      # Start all dev servers
npm run lint     # Run linting across packages

System Requirements

• Node.js: Version 18 or higher
• Package Manager: Any of the following:
  • npm (comes with Node.js)
  • pnpm (install with npm install -g pnpm)
  • Bun (install from bun.sh)
  • Yarn (install with npm install -g yarn)

Verification

After installation, verify that workspace-utils is working by running a script:

npm run build

You should see workspace-utils detect your workspace and execute the build process.

Workspace Requirements

workspace-utils works with any monorepo that has one of the following configurations:

Bun Workspaces

• Root package.json with workspaces field
• bun.lockb file (or bunfig.toml)

{
	"name": "my-monorepo",
	"workspaces": ["packages/*", "apps/*"]
}

pnpm Workspaces

• pnpm-workspace.yaml file
• pnpm-lock.yaml file

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

npm Workspaces

• Root package.json with workspaces field
• package-lock.json file

{
	"name": "my-monorepo",
	"workspaces": ["packages/*", "apps/*"]
}

Next Steps

Once installed, check out the Quick Start guide to begin using workspace-utils in your monorepo.

Troubleshooting Installation

Installation Issues

If you encounter issues during installation:

Clear package manager cache:

# npm
npm cache clean --force

# pnpm
pnpm store prune

# bun
bun pm cache rm

# yarn
yarn cache clean

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Script Not Working

If scripts in package.json don't work:

1. Ensure workspace-utils is installed as a dev dependency
2. Check that your package.json scripts use wsu correctly
3. Run npm ls workspace-utils to verify installation
4. Try running the command directly: npx wsu --version

Quick Start

Get up and running with workspace-utils in minutes. This guide assumes you have a monorepo with workspaces already set up.

Prerequisites

• A monorepo with Bun, pnpm, or npm workspaces
• Node.js 18+ installed
• workspace-utils installed as a dev dependency (Installation Guide)

Setup Your Scripts

First, add workspace-utils scripts to your root package.json:

{
	"scripts": {
		"test": "wsu run test",
		"build": "wsu build",
		"dev": "wsu dev",
		"lint": "wsu run lint"
	}
}

Your First Command

Navigate to your monorepo root and run:

npm run test

This will:

1. 🔍 Auto-detect your package manager (Bun, pnpm, or npm)
2. 📦 Discover all packages in your workspace
3. ✅ Filter to packages that have a test script
4. 🚀 Run tests in parallel across all packages
5. 📊 Display a summary of results

Core Commands

Run Scripts Across Packages

Add these scripts to your package.json:

{
	"scripts": {
		"test": "wsu run test",
		"test:sequential": "wsu run test --sequential",
		"lint": "wsu run lint --concurrency 8"
	}
}

Then run:

npm run test           # Run tests in parallel (default)
npm run test:sequential # Run builds sequentially
npm run lint           # Run linting with custom concurrency

Build with Dependency Awareness

Add build scripts:

{
	"scripts": {
		"build": "wsu build",
		"build:backend": "wsu build --filter '@myorg/backend-*'"
	}
}

Then run:

npm run build         # Build all packages in dependency order
npm run build:backend # Build only backend packages

Start Development Servers

Add dev scripts:

{
	"scripts": {
		"dev": "wsu dev",
		"dev:apps": "wsu dev --filter 'apps/*'"
	}
}

Then run:

npm run dev      # Start all dev servers
npm run dev:apps # Start only frontend packages

Example Walkthrough

Let's say you have this monorepo structure:

my-project/
├── package.json
├── packages/
│   ├── utils/
│   │   └── package.json (scripts: test, build, lint)
│   └── ui-components/
│       └── package.json (scripts: test, build, dev, storybook)
└── apps/
    └── web-app/
        └── package.json (scripts: test, build, dev, start)

Step 1: Run Tests

npm run test

Output:

🚀 Running script "test" across packages...

📁 Workspace root: /Users/you/my-project
📦 Found 3 packages

✅ Running "test" in 3 packages:
  • utils
  • ui-components
  • web-app

🔧 Package manager: npm
⚡ Execution mode: parallel (concurrency: 4)

[utils] Starting: npm run test
[ui-components] Starting: npm run test
[web-app] Starting: npm run test
[utils] ✅ Completed in 1,234ms
[ui-components] ✅ Completed in 2,456ms
[web-app] ✅ Completed in 3,789ms

📊 Execution Summary:
✅ Successful: 3
⏱️  Total duration: 3,789ms

Step 2: Build Everything

npm run build

Output:

🏗️  Building packages in dependency order...

📊 Building dependency graph...
✅ Build order determined: 2 batches

📋 Build Plan:
  Batch 1: utils
  Batch 2: ui-components, web-app

🔧 Package manager: npm
⚡ Batch concurrency: 4

🔄 Running batch 1/2 (1 packages)
[utils] Starting: npm run build
[utils] ✅ Completed in 2,000ms
✅ Batch 1 completed successfully

🔄 Running batch 2/2 (2 packages)
[ui-components] Starting: npm run build
[web-app] Starting: npm run build
[ui-components] ✅ Completed in 3,000ms
[web-app] ✅ Completed in 4,000ms
✅ Batch 2 completed successfully

🎉 All packages built successfully!

Step 3: Start Development

npm run dev

Output:

🚀 Starting development servers with live log streaming...

✅ Starting dev servers for 2 packages:
  • ui-components
  • web-app

🔧 Package manager: npm
⚡ Running 2 dev servers simultaneously

🎬 Starting development servers...

────────────────────────────────────────────────────────
[ui-components] Starting: npm run dev
[web-app] Starting: npm run dev
[ui-components] Server running on http://localhost:6006
[web-app] Server running on http://localhost:3000
[ui-components] Hot reload enabled
[web-app] Hot reload enabled
...

Filtering Examples

Use filtering options in your package.json scripts:

{
	"scripts": {
		"test:scope": "wsu run test --filter '@myorg/*'",
		"build:apps": "wsu build --filter 'apps/*'",
		"dev:frontend": "wsu dev --filter '*frontend*'",
		"lint:utils": "wsu run lint --filter '*utils*'"
	}
}

Then run:

npm run test:scope     # Run tests only for scoped packages
npm run build:apps     # Build only apps
npm run dev:frontend   # Start dev servers for frontend packages
npm run lint:utils     # Run linting for utility packages

Common Patterns

Package.json Scripts

Add these to your root package.json for convenient shortcuts:

{
	"scripts": {
		"test": "wsu run test",
		"test:sequential": "wsu run test --sequential",
		"build": "wsu build",
		"build:frontend": "wsu build --filter 'apps/*'",
		"dev": "wsu dev",
		"lint": "wsu run lint",
		"lint:fix": "wsu run lint:fix"
	}
}

What's Next?

• 📚 Learn about Configuration options
• 🔧 Explore all Commands in detail
• 🎯 Check out Common Patterns
• 🐛 See Troubleshooting if you run into issues

Need Help?

• View all available options: npx wsu --help
• Get help for specific commands: npx wsu run --help
• Check out the CLI Reference for complete documentation

Configuration

workspace-utils is designed to work with zero configuration by default. It automatically detects your workspace setup and package manager, then runs with sensible defaults. However, you can customize behavior through command-line options.

No Configuration Files

Unlike many other tools, workspace-utils does not use configuration files. All behavior is controlled through:

1. Command-line flags (primary method)
2. Workspace structure (automatic detection)
3. Package manager detection (automatic)

This approach keeps things simple and ensures your commands are explicit and reproducible.

Command-Line Configuration

All configuration is done through command-line options. Here are the most commonly used options:

Global Options

Available for all commands:

Command-Specific Options

run command

workspace-utils run <script> [options]

build command

workspace-utils build [options]

dev command

workspace-utils dev [options]

No additional options - uses global options only.

Environment Variables

workspace-utils respects these environment variables:

Package Manager Detection

workspace-utils automatically detects your package manager based on lock files and configuration:

Detection Priority

1. Bun - if bun.lockb exists or bun-specific fields in package.json
2. pnpm - if pnpm-lock.yaml or pnpm-workspace.yaml exists
3. npm - if package-lock.json exists

Workspace Configuration

The tool reads workspace configuration from:

Workspace Structure Requirements

Supported Workspace Formats

Bun Workspaces

{
	"name": "my-monorepo",
	"workspaces": ["packages/*", "apps/*"]
}

pnpm Workspaces

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'
  - '!**/test/**'

npm Workspaces

{
	"name": "my-monorepo",
	"workspaces": {
		"packages": ["packages/*", "apps/*"]
	}
}

Common Configuration Patterns

Package.json Scripts

Add workspace-utils commands to your root package.json:

{
	"scripts": {
		"test": "workspace-utils run test",
		"test:sequential": "workspace-utils run test --sequential",
		"build": "workspace-utils build",
		"build:apps": "workspace-utils build --filter 'apps/*'",
		"dev": "workspace-utils dev",
		"lint": "workspace-utils run lint --concurrency 8",
		"typecheck": "workspace-utils run typecheck --parallel"
	}
}

CI/CD Configuration

Optimize for continuous integration:

# Lower concurrency for CI resources
workspace-utils run test --concurrency 2

# Sequential builds for predictable resource usage
workspace-utils build --concurrency 1

# Parallel linting for speed
workspace-utils run lint --concurrency 4

Development Workflow

Optimize for local development:

# Start all dev servers
workspace-utils dev

# Run tests with higher concurrency on powerful dev machines
workspace-utils run test --concurrency 8

# Filter to work on specific features
workspace-utils dev --filter "*frontend*"

Performance Tuning

Concurrency Guidelines

System Resources

Consider your system when setting concurrency:

# For 4-core machines
workspace-utils run build --concurrency 2

# For 8+ core machines
workspace-utils run test --concurrency 8

# For CI with limited resources
workspace-utils run lint --concurrency 2

Filtering Patterns

Glob Patterns

workspace-utils supports standard glob patterns:

Multiple Filters

Use multiple invocations for complex filtering:

# Run tests on backend packages only
workspace-utils run test --filter "@company/backend-*"

# Build all apps and shared libraries
workspace-utils build --filter "apps/*"
workspace-utils build --filter "@company/shared-*"

Error Handling Configuration

Exit Behavior

workspace-utils has different exit behaviors by command:

Error Codes

Next Steps

• Learn about Workspace Detection
• Explore Package Manager Support
• See Performance Tuning for optimization tips

Commands Overview

workspace-utils provides three main commands designed to handle different aspects of monorepo workflow management. Each command is optimized for specific use cases while sharing common functionality like package filtering and concurrency control.

Command Summary

Quick Reference

wsu run

wsu run <script> [options]

Execute any script across multiple packages in parallel (by default) or sequentially.

Package.json setup:

{
	"scripts": {
		"test": "wsu run test",
		"lint": "wsu run lint --sequential",
		"typecheck": "wsu run typecheck --concurrency 8"
	}
}

Usage:

npm run test       # Run tests in parallel
npm run lint       # Run linting sequentially
npm run typecheck  # Custom concurrency

wsu build

wsu build [options]

Build packages in dependency order using topological sorting. Packages are built in batches where each batch can run in parallel.

Package.json setup:

{
	"scripts": {
		"build": "wsu build",
		"build:apps": "wsu build --filter 'apps/*'",
		"build:slow": "wsu build --concurrency 2"
	}
}

Usage:

npm run build       # Build all packages
npm run build:apps  # Build only apps
npm run build:slow  # Limit batch concurrency

wsu dev

wsu dev [options]

Start development servers with live log streaming. Designed for long-running processes with real-time output.

Package.json setup:

{
	"scripts": {
		"dev": "wsu dev",
		"dev:scope": "wsu dev --filter '@scope/*'",
		"dev:limited": "wsu dev --concurrency 3"
	}
}

Usage:

npm run dev         # Start all dev servers
npm run dev:scope   # Start scoped packages
npm run dev:limited # Limit concurrent servers

Global Options

All commands support these common options:

Filtering

• --filter <pattern> - Filter packages using glob patterns
• Examples: "@scope/*", "apps/*", "*-utils", "*frontend*"

Concurrency

• --concurrency <number> - Maximum concurrent processes (default: 4)
• Applies to parallel execution and batch processing

Help

• --help - Show command-specific help and options

Execution Modes

Parallel Execution

Used by: run (default), dev Behavior: All matching packages execute simultaneously Best for: Tests, linting, development servers

npm run test  # with "test": "wsu run test" in package.json
# ✅ Runs tests in all packages at the same time

Sequential Execution

Used by: run (with --sequential flag) Behavior: Packages execute one after another Best for: Resource-intensive tasks, ordered operations

npm run build:sequential  # with "build:sequential": "wsu run build --sequential"
# ✅ Runs builds one package at a time

Dependency-Aware Execution

Used by: build Behavior: Packages are grouped into batches based on dependencies Best for: Building, publishing, dependency-critical operations

npm run build  # with "build": "wsu build" in package.json
# ✅ Builds dependencies first, then dependents

Package Manager Detection

workspace-utils automatically detects your package manager:

The detected package manager is used for all script execution (e.g., bun run test, pnpm run test, npm run test).

Error Handling

Exit Behavior

• Single failure in parallel mode: Other packages continue running
• Single failure in sequential mode: Execution stops immediately
• Single failure in build mode: Current batch fails, subsequent batches are skipped

Exit Codes

• 0 - All packages executed successfully
• 1 - One or more packages failed
• 2 - Configuration or setup error

Output Format

All commands provide consistent, color-coded output:

🚀 Starting operation...
📁 Workspace root: /path/to/workspace
📦 Found X packages
✅ Running "script" in Y packages
🔧 Package manager: detected-pm
⚡ Execution mode: parallel/sequential/dependency-order

[package-1] Starting: pm run script
[package-2] Starting: pm run script
[package-1] ✅ Completed in 1,234ms
[package-2] ❌ Failed with exit code 1

📊 Execution Summary:
✅ Successful: 1
❌ Failed: 1
⏱️  Total duration: 2,345ms

Best Practices

Choose the Right Command

• run for most script execution (tests, linting, utilities)
• build when package dependencies matter
• dev for long-running development processes

Use Filtering Effectively

{
	"scripts": {
		"test:packages": "wsu run test --filter 'packages/*'",
		"dev:apps": "wsu dev --filter 'apps/*'",
		"build:company": "wsu build --filter '@company/*'"
	}
}

Optimize Concurrency

{
	"scripts": {
		"build:slow": "wsu run build --concurrency 2",
		"test:fast": "wsu run test --concurrency 8",
		"dev": "wsu dev --concurrency 4"
	}
}

Next Steps

Dive deeper into each command:

• run command - Detailed script execution options
• build command - Dependency-aware building
• dev command - Development server management

run Command

The run command executes scripts across multiple packages in your workspace, with parallel execution by default.

Recommended Usage

Add to your package.json scripts:

{
	"scripts": {
		"test": "wsu run test",
		"lint": "wsu run lint",
		"typecheck": "wsu run typecheck"
	}
}

Then run:

npm run test     # Run tests across packages
npm run lint     # Run linting across packages
npm run typecheck # Run type checking across packages

Direct Usage (if needed)

wsu run <script> [options]

Arguments

• <script> - The npm script name to execute (e.g., test, lint, build)

Options

Examples

Basic Usage

Add scripts to your package.json:

{
	"scripts": {
		"test": "wsu run test",
		"test:sequential": "wsu run test --sequential",
		"lint": "wsu run lint --concurrency 8"
	}
}

Then run:

npm run test            # Run tests in parallel (default)
npm run test:sequential # Run tests sequentially
npm run lint            # Run linting with custom concurrency

Package Filtering

Add filtered scripts to your package.json:

{
	"scripts": {
		"test:company": "wsu run test --filter '@company/*'",
		"dev:apps": "wsu run dev --filter 'apps/*'",
		"build:backend": "wsu run build --filter '*backend*'"
	}
}

Then run:

npm run test:company   # Run tests for scoped packages
npm run dev:apps       # Run dev scripts for apps only
npm run build:backend  # Run builds for backend packages

Example Output

🚀 Running script "test" across packages...

📦 Found 3 packages
✅ Running "test" in 3 packages:
  • @company/utils
  • @company/ui-components
  • apps/web-app

🔧 Package manager: pnpm
⚡ Execution mode: parallel (concurrency: 4)

[@company/utils] Starting: pnpm run test
[@company/ui-components] Starting: pnpm run test
[apps/web-app] Starting: pnpm run test
[@company/utils] ✅ Completed in 1,234ms
[@company/ui-components] ✅ Completed in 2,456ms
[apps/web-app] ✅ Completed in 3,789ms

📊 Execution Summary:
✅ Successful: 3
⏱️  Total duration: 3,789ms

Execution Modes

Parallel (Default)

• Runs all packages simultaneously
• Faster for I/O bound tasks like tests and linting
• Other packages continue if one fails

Sequential

• Runs packages one at a time
• Stops on first failure
• Better for resource-intensive tasks

When to Use

• Tests - Parallel execution for fast feedback
• Linting - High concurrency for quick checks
• Type checking - Parallel across packages
• Custom scripts - Any script that exists in package.json

Package.json Integration

Add common patterns to your root package.json:

{
	"scripts": {
		"test": "wsu run test",
		"test:watch": "wsu run test:watch",
		"lint": "wsu run lint --concurrency 8",
		"lint:fix": "wsu run lint:fix",
		"typecheck": "wsu run typecheck",
		"clean": "wsu run clean --sequential"
	}
}

build Command

The build command builds packages in dependency order, ensuring that dependencies are built before their dependents.

Recommended Usage

Add to your package.json scripts:

{
	"scripts": {
		"build": "wsu build",
		"build:apps": "wsu build --filter 'apps/*'",
		"build:slow": "wsu build --concurrency 2"
	}
}

Then run:

npm run build      # Build all packages in dependency order
npm run build:apps # Build only apps
npm run build:slow # Build with limited concurrency

Direct Usage (if needed)

wsu build [options]

How it Works

1. Analyzes dependencies - Reads package.json files to understand package relationships
2. Creates build batches - Groups packages that can be built in parallel
3. Executes in order - Runs builds batch by batch, respecting dependencies

Options

Examples

Basic Usage

Add scripts to your package.json:

{
	"scripts": {
		"build": "wsu build",
		"build:apps": "wsu build --filter 'apps/*'",
		"build:limited": "wsu build --concurrency 2"
	}
}

Then run:

npm run build         # Build all packages in dependency order
npm run build:apps    # Build only apps
npm run build:limited # Build with limited concurrency

Example Output

🏗️  Building packages in dependency order...

📊 Building dependency graph...
✅ Build order determined: 3 batches

📋 Build Plan:
  Batch 1: @company/utils
  Batch 2: @company/ui-components, @company/api-client
  Batch 3: apps/web-app

🔧 Package manager: pnpm
⚡ Batch concurrency: 4

🔄 Running batch 1/3 (1 packages)
[@company/utils] ✅ Completed in 2,000ms

🔄 Running batch 2/3 (2 packages)
[@company/ui-components] ✅ Completed in 3,000ms
[@company/api-client] ✅ Completed in 2,500ms

🔄 Running batch 3/3 (1 packages)
[apps/web-app] ✅ Completed in 4,000ms

🎉 All packages built successfully!

When to Use

• Production builds - When dependency order matters
• CI/CD pipelines - Reliable, predictable builds
• Publishing - Ensure dependencies are built first
• Clean builds - Start from scratch with proper ordering

Error Handling

• If a package fails, the current batch stops
• Subsequent batches are skipped
• Exit code is non-zero if any builds fail

dev Command

The dev command starts development servers across multiple packages with live log streaming and graceful shutdown.

Recommended Usage

Add to your package.json scripts:

{
	"scripts": {
		"dev": "wsu dev",
		"dev:apps": "wsu dev --filter 'apps/*'",
		"dev:limited": "wsu dev --concurrency 2"
	}
}

Then run:

npm run dev         # Start all dev servers
npm run dev:apps    # Start only frontend packages
npm run dev:limited # Limit concurrent servers

Direct Usage (if needed)

wsu dev [options]

How it Works

1. Finds packages with dev scripts
2. Starts servers in parallel with live log streaming
3. Color-codes output for easy identification
4. Handles shutdown gracefully when you press Ctrl+C

Options

Examples

Basic Usage

Add scripts to your package.json:

{
	"scripts": {
		"dev": "wsu dev",
		"dev:frontend": "wsu dev --filter 'apps/*'",
		"dev:limited": "wsu dev --concurrency 2"
	}
}

Then run:

npm run dev          # Start all dev servers
npm run dev:frontend # Start only frontend packages
npm run dev:limited  # Limit concurrent servers

Example Output

🚀 Starting development servers with live log streaming...

✅ Starting dev servers for 3 packages:
  • @company/ui-components
  • apps/web-app
  • apps/mobile-app

🔧 Package manager: npm
⚡ Running 3 dev servers simultaneously
💡 Tip: Use Ctrl+C to stop all development servers

🎬 Starting development servers...

────────────────────────────────────────────────────────
[@company/ui-components] Starting: npm run dev
[apps/web-app] Starting: npm run dev
[apps/mobile-app] Starting: npm run dev
[@company/ui-components] Server running on http://localhost:6006
[apps/web-app] Server running on http://localhost:3000
[apps/mobile-app] Expo running on http://localhost:19000
[@company/ui-components] Hot reload enabled
[apps/web-app] Hot reload enabled
...

Features

• Live log streaming - See real-time output from all servers
• Color-coded prefixes - Each package has its own color
• Graceful shutdown - Ctrl+C stops all servers cleanly
• No timestamps - Clean output focused on development

When to Use

• Local development - Start all services at once
• Full-stack development - Frontend, backend, and services together
• Debugging - See logs from multiple packages simultaneously
• Team development - Consistent development environment

Tips

• Use filtering to start only the packages you're working on
• Keep concurrency reasonable to avoid overwhelming your system
• Each package gets a unique color for easy log identification
• Press Ctrl+C once to gracefully stop all servers

Examples

This page provides comprehensive examples of using workspace-utils in real-world scenarios. Each example includes the monorepo structure, commands, and expected output.

Example 1: Full-Stack JavaScript Application

Project Structure

my-fullstack-app/
├── package.json (workspaces)
├── packages/
│   ├── shared-types/      # TypeScript definitions
│   ├── ui-components/     # React component library
│   ├── api-client/        # REST API client
│   └── utils/             # Shared utilities
└── apps/
    ├── web-app/           # Next.js frontend
    ├── mobile-app/        # React Native
    └── api-server/        # Express.js backend

Common Workflows

Run All Tests

Add to your package.json:

{
	"scripts": {
		"test": "wsu run test"
	}
}

Then run:

npm run test

Output:

🚀 Running script "test" across packages...

📦 Found 7 packages
✅ Running "test" in 6 packages:
  • packages/shared-types
  • packages/ui-components
  • packages/api-client
  • packages/utils
  • apps/web-app
  • apps/api-server

🔧 Package manager: pnpm
⚡ Execution mode: parallel (concurrency: 4)

[packages/utils] ✅ Completed in 1,200ms
[packages/shared-types] ✅ Completed in 800ms
[packages/api-client] ✅ Completed in 2,100ms
[packages/ui-components] ✅ Completed in 3,400ms
[apps/api-server] ✅ Completed in 2,800ms
[apps/web-app] ✅ Completed in 4,200ms

📊 Execution Summary:
✅ Successful: 6
⏱️  Total duration: 4,200ms

Build Everything in Dependency Order

Add to your package.json:

{
	"scripts": {
		"build": "wsu build"
	}
}

Then run:

npm run build

Output:

🏗️  Building packages in dependency order...

📊 Building dependency graph...
✅ Build order determined: 4 batches

📋 Build Plan:
  Batch 1: packages/shared-types, packages/utils
  Batch 2: packages/ui-components, packages/api-client
  Batch 3: apps/api-server
  Batch 4: apps/web-app, apps/mobile-app

🔧 Package manager: pnpm
⚡ Batch concurrency: 4

🔄 Running batch 1/4 (2 packages)
[packages/shared-types] ✅ Completed in 1,500ms
[packages/utils] ✅ Completed in 1,200ms

🔄 Running batch 2/4 (2 packages)
[packages/ui-components] ✅ Completed in 8,900ms
[packages/api-client] ✅ Completed in 3,200ms

🔄 Running batch 3/4 (1 packages)
[apps/api-server] ✅ Completed in 4,100ms

🔄 Running batch 4/4 (2 packages)
[apps/web-app] ✅ Completed in 12,300ms
[apps/mobile-app] ✅ Completed in 8,700ms

🎉 All packages built successfully!

Start Development Environment

Add to your package.json:

{
	"scripts": {
		"dev": "wsu dev"
	}
}

Then run:

npm run dev

Output:

🚀 Starting development servers with live log streaming...

✅ Starting dev servers for 4 packages:
  • packages/ui-components
  • apps/web-app
  • apps/mobile-app
  • apps/api-server

🔧 Package manager: pnpm
⚡ Running 4 dev servers simultaneously
💡 Tip: Use Ctrl+C to stop all development servers

[packages/ui-components] Storybook running on http://localhost:6006
[apps/api-server] Server running on http://localhost:4000
[apps/web-app] Next.js running on http://localhost:3000
[apps/mobile-app] Expo running on http://localhost:19000
[apps/web-app] Hot reload enabled
[packages/ui-components] Hot reload enabled
[apps/api-server] Watching for changes...
[apps/mobile-app] Metro bundler started
...

Example 2: Design System Monorepo

Project Structure

design-system/
├── packages/
│   ├── tokens/            # Design tokens
│   ├── icons/             # Icon library
│   ├── components/        # React components
│   ├── themes/            # Theme definitions
│   └── utils/             # Design utilities
├── apps/
│   ├── storybook/         # Component documentation
│   └── playground/        # Component testing
└── tools/
    └── build-tools/       # Custom build scripts

Workflows

Build Design System

Add to your package.json:

{
	"scripts": {
		"build": "wsu build",
		"build:tokens": "wsu build --filter 'packages/tokens'",
		"build:icons": "wsu build --filter 'packages/icons'",
		"test:visual": "wsu run test:visual --concurrency 2",
		"lint": "wsu run lint --concurrency 8"
	}
}

Then run:

npm run build:tokens  # Build tokens first
npm run build:icons   # Then icons
npm run build         # Then everything else
npm run test:visual   # Visual regression tests
npm run lint          # Lint all code

Example 3: Microservices Architecture

Project Structure

microservices/
├── shared/
│   ├── types/             # Shared TypeScript types
│   ├── configs/           # Shared configurations
│   └── middleware/        # Common middleware
├── services/
│   ├── auth-service/      # Authentication
│   ├── user-service/      # User management
│   ├── payment-service/   # Payment processing
│   ├── notification-service/ # Notifications
│   └── gateway-service/   # API Gateway
└── tools/
    ├── docker-compose/    # Container orchestration
    └── deployment/        # Deployment scripts

Workflows

Service Workflows

Add to your package.json:

{
	"scripts": {
		"test:services": "wsu run test --filter 'services/*'",
		"build:shared": "wsu build --filter 'shared/*'",
		"build:services": "wsu build --filter 'services/*' --sequential",
		"dev:services": "wsu dev --filter 'services/*' --concurrency 6"
	}
}

Then run:

npm run test:services  # Run tests for all services
npm run build:shared   # Build shared libraries first
npm run build:services # Then build all services
npm run dev:services   # Start local development

Example 4: Multi-Platform Mobile App

Project Structure

mobile-app/
├── packages/
│   ├── core/              # Business logic
│   ├── ui/                # Shared UI components
│   ├── api/               # API layer
│   └── utils/             # Utilities
├── apps/
│   ├── ios/               # iOS app
│   ├── android/           # Android app
│   └── web/               # Web version
└── tools/
    ├── build-scripts/     # Platform build tools
    └── testing/           # Testing utilities

Platform-Specific Workflows

Platform-Specific Workflows

Add to your package.json:

{
	"scripts": {
		"dev:ios": "wsu dev --filter 'apps/ios' --filter 'packages/*'",
		"dev:android": "wsu dev --filter 'apps/android' --filter 'packages/*'",
		"test:core": "wsu run test --filter 'packages/*'",
		"test:ios": "wsu run test:ios --filter 'apps/ios'",
		"test:android": "wsu run test:android --filter 'apps/android'"
	}
}

Then run:

npm run dev:ios       # iOS development
npm run dev:android   # Android development
npm run test:core     # Test core logic
npm run test:ios      # Test iOS specifically
npm run test:android  # Test Android specifically

Example 5: Enterprise Library Collection

Project Structure

enterprise-libs/
├── core/
│   ├── auth/              # Authentication library
│   ├── logging/           # Logging utilities
│   ├── validation/        # Data validation
│   └── storage/           # Storage abstractions
├── ui/
│   ├── react-components/  # React component library
│   ├── vue-components/    # Vue component library
│   └── angular-components/ # Angular component library
└── integrations/
    ├── aws-integration/   # AWS utilities
    ├── gcp-integration/   # Google Cloud utilities
    └── azure-integration/ # Azure utilities

Library Publishing Workflow

Library Publishing Workflow

Add to your package.json:

{
	"scripts": {
		"test": "wsu run test",
		"build": "wsu build",
		"publish": "wsu run publish --sequential",
		"test:react": "wsu run test --filter '*react*'",
		"test:vue": "wsu run test --filter '*vue*'",
		"test:angular": "wsu run test --filter '*angular*'"
	}
}

Then run:

npm run test          # Run all tests first
npm run build         # Build everything
npm run publish       # Publish packages
npm run test:react    # Test React components
npm run test:vue      # Test Vue components
npm run test:angular  # Test Angular components

Example 6: Documentation Site

Project Structure

docs-site/
├── content/
│   ├── guides/            # User guides
│   ├── api-docs/          # API documentation
│   └── examples/          # Code examples
├── tools/
│   ├── markdown-processor/ # Custom markdown tools
│   ├── code-generator/    # Generate code samples
│   └── link-checker/      # Validate links
└── sites/
    ├── main-site/         # Main documentation
    ├── blog/              # Blog site
    └── api-reference/     # API reference site

Documentation Workflows

Documentation Workflows

Add to your package.json:

{
	"scripts": {
		"docs:generate": "wsu run generate --filter 'tools/*'",
		"docs:build": "wsu build --filter 'sites/*'",
		"docs:dev": "wsu dev --filter 'sites/*'",
		"docs:validate": "wsu run validate --filter 'tools/link-checker'",
		"docs:spellcheck": "wsu run spellcheck --sequential"
	}
}

Then run:

npm run docs:generate    # Generate content first
npm run docs:build       # Then build sites
npm run docs:dev         # Development with live reload
npm run docs:validate    # Check links and content
npm run docs:spellcheck  # Spell check

Filtering Patterns Reference

Scope-Based Filtering

Add to your package.json:

{
	"scripts": {
		"test:company": "wsu run test --filter '@company/*'",
		"build:internal": "wsu build --filter '@internal/*'"
	}
}

Directory-Based Filtering

{
	"scripts": {
		"dev:apps": "wsu dev --filter 'apps/*'",
		"lint:packages": "wsu run lint --filter 'packages/*'",
		"build:tools": "wsu run build --filter 'tools/*'"
	}
}

Name Pattern Filtering

{
	"scripts": {
		"test:backend": "wsu run test --filter '*backend*'",
		"dev:frontend": "wsu dev --filter '*frontend*'",
		"build:utils": "wsu build --filter '*utils*'",
		"lint:test": "wsu run lint --filter '*test*'"
	}
}

Combined Filtering Examples

{
	"scripts": {
		"test:backend-services": "wsu run test --filter 'services/*backend*'",
		"build:react": "wsu run build --filter '*react*'"
	}
}

Package.json Script Patterns

Basic Setup

{
	"scripts": {
		"test": "wsu run test",
		"build": "wsu build",
		"dev": "wsu dev",
		"lint": "wsu run lint"
	}
}

Advanced Patterns

{
	"scripts": {
		"test": "wsu run test",
		"test:watch": "wsu run test:watch",
		"test:coverage": "wsu run test:coverage",
		"build": "wsu build",
		"build:prod": "wsu build --concurrency 2",
		"dev": "wsu dev",
		"dev:apps": "wsu dev --filter 'apps/*'",
		"lint": "wsu run lint --concurrency 8",
		"lint:fix": "wsu run lint:fix",
		"typecheck": "wsu run typecheck",
		"clean": "wsu run clean --sequential"
	}
}

Performance Optimization Examples

Resource-Constrained Environments

Add to your package.json:

{
	"scripts": {
		"test:ci": "wsu run test --concurrency 1",
		"build:low-mem": "wsu build --concurrency 2",
		"lint:fast": "wsu run lint --concurrency 12"
	}
}

High-Performance Development

{
	"scripts": {
		"test:fast": "wsu run test --concurrency 8",
		"build:fast": "wsu build --concurrency 6",
		"typecheck:fast": "wsu run typecheck --concurrency 16"
	}
}

Troubleshooting Common Scenarios

Mixed Package Managers

If your monorepo accidentally has mixed lock files:

# This will fail with clear error message
npm run test

# Clean up mixed lock files first
rm -f package-lock.json yarn.lock  # Keep only pnpm-lock.yaml
npm run test  # Now works

Missing Scripts

If some packages don't have the script you're trying to run:

# This automatically skips packages without 'storybook' script
npm run storybook

# Output shows which packages were skipped
# ⚠️  Skipped 3 packages without 'storybook' script

Build Dependencies

If builds fail due to missing dependencies:

# Use build command instead of run for dependency-aware building
npm run build  # ✅ Builds in correct order

# Instead of this which might fail
npm run build:parallel  # ❌ Might fail due to missing dependencies

Next Steps

• Explore Command Reference for detailed options
• Learn about Troubleshooting common issues
• See Advanced Usage for complex scenarios

Troubleshooting

This page covers common issues you might encounter when using workspace-utils and how to resolve them.

Installation Issues

Package Not Found

If you get errors about workspace-utils not being found:

# Check if it's installed
npm ls workspace-utils

# If not installed, add it as a dev dependency
npm install --save-dev workspace-utils

# Verify it's in your package.json
cat package.json | grep workspace-utils

Permission Errors

If you encounter permission errors:

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Version Conflicts

If you have conflicting versions:

# Check installed version
npm ls workspace-utils

# Update to latest version
npm install --save-dev workspace-utils@latest

Workspace Detection Issues

No Workspace Found

If workspace-utils can't detect your workspace:

Error: No workspace configuration found

Solution: Ensure you have one of these files in your root:

• pnpm-workspace.yaml (for pnpm)
• package.json with workspaces field (for npm/Bun)

Example for pnpm:

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

Example for npm/Bun:

{
	"workspaces": ["packages/*", "apps/*"]
}

Mixed Package Managers

If you have multiple lock files:

Error: Multiple package managers detected

Solution: Remove conflicting lock files:

# Keep only one lock file type
rm package-lock.json yarn.lock  # Keep pnpm-lock.yaml
# OR
rm pnpm-lock.yaml yarn.lock      # Keep package-lock.json
# OR
rm pnpm-lock.yaml package-lock.json  # Keep yarn.lock

Wrong Package Manager Detected

If the wrong package manager is detected:

Check detection logic:

1. Bun: bun.lockb exists
2. pnpm: pnpm-lock.yaml or pnpm-workspace.yaml exists
3. npm: package-lock.json exists

Solution: Remove unwanted lock files or use the correct package manager for your setup.

Script Execution Issues

No Packages Found with Script

If you get No packages found with the "script-name" script:

Check which packages have the script:

# Manually check package.json files
find . -name "package.json" -not -path "./node_modules/*" -exec grep -l "script-name" {} \;

Solution: Add the script to package.json files where needed:

{
	"scripts": {
		"test": "jest",
		"build": "tsc",
		"dev": "vite dev"
	}
}

Scripts Failing

If individual package scripts fail:

Debug a specific package:

# Navigate to the failing package
cd packages/failing-package

# Run the script directly
npm run script-name

Common issues:

• Missing dependencies: npm install
• TypeScript errors: Check tsconfig.json
• Build output conflicts: npm run clean first

Permission Denied Errors

If you get permission errors running scripts:

# On macOS/Linux, ensure scripts are executable
find . -name "*.sh" -exec chmod +x {} \;

# Check if using the right Node.js version
node --version
npm --version

Build Issues

Dependency Cycle Detected

If you get circular dependency errors:

Error: Dependency cycle detected: package-a -> package-b -> package-a

Solution: Review and break circular dependencies:

1. Check dependencies and devDependencies in package.json files
2. Consider extracting shared code to a separate package
3. Use peerDependencies where appropriate

Debug dependency graph:

# Create a simple script to visualize dependencies
# deps.js
const fs = require('fs');
const path = require('path');

// Find all package.json files and show dependencies
// ... (custom script to analyze dependencies)

Build Order Issues

If builds fail due to missing dependencies:

Use wsu build instead of wsu run build:

{
	"scripts": {
		"build": "wsu build", // ✅ Dependency-aware
		"build:parallel": "wsu run build" // ❌ May fail
	}
}

Memory Issues During Build

If builds run out of memory:

{
	"scripts": {
		"build": "wsu build --concurrency 1",
		"build:heavy": "NODE_OPTIONS='--max-old-space-size=4096' wsu build --concurrency 2"
	}
}

Development Server Issues

Ports Already in Use

If dev servers can't start due to port conflicts:

Check what's using ports:

# On macOS/Linux
lsof -i :3000
lsof -i :4000

# On Windows
netstat -ano | findstr :3000

Solution: Kill conflicting processes or change ports in package.json:

{
	"scripts": {
		"dev": "vite dev --port 3001"
	}
}

Dev Servers Not Starting

If development servers fail to start:

Check individual packages:

cd packages/problematic-package
npm run dev

Common issues:

• Missing dev dependencies
• Incorrect script configuration
• Environment variable issues

Hot Reload Not Working

If hot reload isn't working across packages:

Ensure proper file watching:

• Check if files are being watched correctly
• Verify symlinks are set up properly
• Check if your bundler supports monorepo setups

Performance Issues

Slow Execution

If commands are running slowly:

Reduce concurrency:

{
	"scripts": {
		"test:slow": "wsu run test --concurrency 2",
		"build:slow": "wsu build --concurrency 1"
	}
}

Use filtering to run fewer packages:

{
	"scripts": {
		"test:changed": "wsu run test --filter 'packages/changed-*'",
		"dev:minimal": "wsu dev --filter 'apps/main-app'"
	}
}

High Memory Usage

If workspace-utils uses too much memory:

# Monitor memory usage
top -p $(pgrep -f workspace-utils)

# Reduce concurrency
# Add to package.json scripts
"build:low-mem": "wsu build --concurrency 1"

Character Encoding Issues

Garbled Characters in Output

If you see strange characters instead of emojis:

Examples of issues:

â Completed in 54428ms    # Should be ✅ or [OK]
â±ï¸  Total build time    # Should be ⏱️ or [TIME]
â ï¸ Warning message      # Should be ⚠️ or [WARN]

Quick Solutions:

Option 1: Force ASCII mode (recommended)

{
	"scripts": {
		"build": "wsu build --ascii",
		"test": "wsu run test --ascii",
		"dev": "wsu dev --ascii"
	}
}

Option 2: Set environment variable

# In your shell
export WSU_ASCII=1

# Or in package.json
"build": "WSU_ASCII=1 wsu build"

Option 3: Terminal fixes If you prefer Unicode characters:

1. Update your terminal to a modern version
2. Set proper environment variables:

   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8
   

3. Force Unicode mode:

   export WSU_UNICODE=1
   

Debug what's being detected:

# Check your environment
node -e "console.log(process.platform, process.env.TERM, process.env.TERM_PROGRAM)"

Filtering Issues

Filter Not Matching Packages

If --filter doesn't match expected packages:

Debug filtering:

# List all packages first
find . -name "package.json" -not -path "./node_modules/*" | head -10

# Check package names in workspace

Common filter patterns:

{
	"scripts": {
		"test:scope": "wsu run test --filter '@company/*'",
		"test:apps": "wsu run test --filter 'apps/*'",
		"test:utils": "wsu run test --filter '*-utils'",
		"test:frontend": "wsu run test --filter '*frontend*'"
	}
}

Case Sensitivity

Filters are case-sensitive. Use exact casing:

{
	"scripts": {
		"test:React": "wsu run test --filter '*React*'", // Correct
		"test:react": "wsu run test --filter '*react*'" // Different results
	}
}

Environment Issues

Node.js Version

workspace-utils requires Node.js 18+:

# Check version
node --version

# If too old, update Node.js
# Use nvm, fnm, or download from nodejs.org

Environment Variables

If environment variables aren't being passed:

In your package scripts:

{
	"scripts": {
		"test:env": "NODE_ENV=test wsu run test",
		"build:prod": "NODE_ENV=production wsu build"
	}
}

For complex environments, use .env files in individual packages.

Getting Help

Enable Debug Mode

If you need more information about what's happening:

{
	"scripts": {
		"debug:build": "DEBUG=workspace-utils wsu build",
		"debug:test": "DEBUG=* wsu run test"
	}
}

Verbose Output

For more detailed logging:

# Run with verbose npm logging
npm run build --verbose

# Check the exact commands being run

Common Command Issues

Command not found:

# Make sure workspace-utils is installed
npm ls workspace-utils

# Try running directly
npx wsu --version

Script syntax errors:

{
	"scripts": {
		// ❌ Wrong quotes
		"test": "wsu run test",

		// ✅ Correct quotes
		"test": "wsu run test"
	}
}

Reporting Issues

If you encounter a bug or need help:

1. Check this troubleshooting guide first
2. Search existing issues in the repository
3. Provide minimal reproduction when reporting:
   • Your package.json scripts
   • Workspace structure
   • Full error message
   • Node.js and package manager versions

Useful info to include:

# System information
node --version
npm --version  # or pnpm --version, bun --version
npx wsu --version

# Workspace structure
tree -I node_modules -L 3

Quick Fixes Checklist

When things go wrong, try these in order:

1. Check installation: npm ls workspace-utils
2. Verify workspace setup: Ensure workspace config files exist
3. Clean and reinstall: rm -rf node_modules && npm install
4. Check package.json syntax: Ensure scripts are properly quoted
5. Test individual packages: cd package && npm run script-name
6. Reduce concurrency: Add --concurrency 1 to scripts
7. Check Node.js version: node --version (should be 18+)
8. Clear caches: npm cache clean --force

Most issues are resolved by steps 1-4!