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]

cache command

workspace-utils cache [command]

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/*'",
		"build:all": "workspace-utils build --no-skip-unchanged",
		"dev": "workspace-utils dev",
		"lint": "workspace-utils run lint --concurrency 8",
		"typecheck": "workspace-utils run typecheck --parallel",
		"cache:clear": "workspace-utils cache clear"
	}
}

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

Build Caching

The build command includes intelligent caching to skip unchanged packages:

How Caching Works

• Content hashing - SHA256 hashes of source files and package.json
• Git-aware - Only tracks files not ignored by .gitignore
• Dependency tracking - Cache invalidated when dependencies change
• Automatic management - Cache stored in .wsu/ (auto-added to .gitignore)

Cache Configuration

Caching is enabled by default. Control it with:

# Build with caching (default) - skips unchanged packages
workspace-utils build

# Build all packages (disable caching)
workspace-utils build --no-skip-unchanged

Cache Management Commands

# View cache status and statistics
workspace-utils cache

# Clear all cached builds
workspace-utils cache clear

When to Disable Caching

• Clean builds - When you want to ensure everything rebuilds
• CI/CD - Some pipelines prefer full builds for consistency
• Debugging - When investigating build issues

CI/CD Caching Strategy

# For CI with caching (faster incremental builds)
workspace-utils build

# For release builds (full rebuild)
workspace-utils build --no-skip-unchanged

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 four 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

wsu clean

wsu clean [options]

Remove node_modules directories from the workspace root and all packages.

Package.json setup:

{
	"scripts": {
		"clean": "wsu clean",
		"clean:apps": "wsu clean --filter 'apps/*'",
		"reinstall": "wsu clean && npm install"
	}
}

Usage:

npm run clean       # Remove all node_modules
npm run clean:apps  # Clean only app packages
npm run reinstall   # Clean and reinstall

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
• clean to remove node_modules for fresh installs

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
• clean command - Remove node_modules directories

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. Checks cache - Skips packages that haven't changed since last successful build
3. Creates build batches - Groups packages that can be built in parallel
4. Executes in order - Runs builds batch by batch, respecting dependencies
5. Updates cache - Stores successful build metadata for future runs

Options

Build Caching

By default, the build command uses intelligent caching to skip unchanged packages:

How Caching Works

• Content hashing - Tracks changes to source files and package.json
• Dependency tracking - Rebuilds packages when their dependencies change
• Automatic invalidation - Cache is invalidated when source files or dependencies change
• Git-aware - Only tracks files not ignored by git

Cache Location

Cache is stored in .wsu/ directory (automatically added to .gitignore):

.wsu/
├── manifest.json
└── packages/
    └── <package-name>/
        ├── cache.json
        └── files.json

Disabling Cache

To build all packages regardless of cache:

wsu build --no-skip-unchanged

Managing Cache

Use the cache command to manage cached builds:

# View cache status
wsu cache

# Clear all cached builds
wsu cache clear

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",
		"build:all": "wsu build --no-skip-unchanged"
	}
}

Then run:

npm run build         # Build all packages (uses cache)
npm run build:apps    # Build only apps
npm run build:limited # Build with limited concurrency
npm run build:all     # Force build all packages

With Caching

First build (all packages):

🏗️  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!

Second build (unchanged packages skipped):

🏗️  Building packages in dependency order...
📊 Build dependency graph...
✅ 3 packages unchanged (cached) - skipping build
  - @company/utils
  - @company/ui-components
  - @company/api-client

📊 Building 1 packages:
  - apps/web-app

🔄 Running batch 1/1 (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
• Development - Fast incremental builds with caching

Error Handling

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

See Also

• cache command - Manage build cache
• run command - Run arbitrary scripts

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

cache Command

The cache command manages the build cache used by the build command to skip unchanged packages.

Recommended Usage

No need to add to package.json - use directly when needed:

# Check cache status
wsu cache

# Clear the cache
wsu cache clear

Direct Usage

wsu cache [command]

Commands

How Caching Works

The build cache automatically:

1. Tracks package content - Hashes source files and package.json for each package
2. Monitors dependencies - Invalidates cache when dependencies change
3. Skips unchanged builds - Skips packages that haven't changed since last successful build
4. Auto-manages storage - Stores cache in .wsu/ directory (auto-added to .gitignore)

Cache Location

.wsu/
├── manifest.json          # Cache manifest
└── packages/
    ├── package-a/
    │   ├── cache.json     # Build metadata
    │   └── files.json     # File hashes
    └── package-b/
        ├── cache.json
        └── files.json

Examples

View Cache Status

wsu cache

Output:

📊 Build Cache Status

Workspace root: /path/to/workspace
Total packages in workspace: 5

✅ Cached packages: 3

Cache location: .wsu/packages/<package>/

Cached packages:
  ✓ @company/utils - 2.3s
  ✓ @company/ui - 1.8s
  ○ @company/app - not cached

Clear Cache

wsu cache clear

Output:

🔥 Clearing build cache (3 packages)...
✅ Build cache cleared successfully!

When to Clear Cache

Clear the cache when:

• Build issues - Suspect stale cache is causing problems
• Clean slate - Want to ensure all packages rebuild from scratch
• CI/CD - Some pipelines clear cache periodically for consistency

Caching Behavior

Automatic Invalidation

The cache is automatically invalidated when:

• Source files change (monitored via git)
• package.json is modified
• Dependencies are rebuilt
• Build fails (cache only updated on success)

Build Command Integration

The build command uses caching by default:

# Build with caching (skips unchanged packages)
wsu build

# Build all packages (disable caching)
wsu build --no-skip-unchanged

Cache Statistics

The status command shows:

• Total cached packages - Number of packages with valid cache
• Last updated - When cache was last modified
• Build times - Duration of cached builds
• Uncached packages - Packages that need building

Troubleshooting

Cache not being used

Ensure packages have a build script in their package.json:

{
	"scripts": {
		"build": "your-build-command"
	}
}

Cache files in git

The .wsu/ directory should be in .gitignore. If not, run:

wsu cache clear

Then check your .gitignore was updated.

See Also

• build command - Uses caching by default
• Configuration - Performance tuning options

clean Command

The clean command removes node_modules directories across all packages in your workspace.

Recommended Usage

Add to your package.json scripts:

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

Then run:

npm run clean       # Remove all node_modules
npm run clean:apps  # Clean only app packages

Direct Usage (if needed)

wsu clean [options]

How it Works

1. Parses workspace to find all packages
2. Removes root node_modules (unless filtering)
3. Removes node_modules from each package directory
4. Reports summary with count of cleaned directories

Options

Examples

Basic Usage

Add scripts to your package.json:

{
	"scripts": {
		"clean": "wsu clean",
		"clean:libs": "wsu clean --filter 'packages/*'",
		"clean:apps": "wsu clean --filter 'apps/*'"
	}
}

Then run:

npm run clean       # Clean everything
npm run clean:libs  # Clean only library packages
npm run clean:apps  # Clean only application packages

Example Output

> Cleaning node_modules across packages...

[DIR] Workspace root: /path/to/workspace
[PKG] Found 5 packages

[BOOM] Removing /path/to/workspace/node_modules
[BOOM] Removing @company/ui-components/node_modules
[BOOM] Removing @company/utils/node_modules
[BOOM] Removing apps/web-app/node_modules
[BOOM] Removing apps/mobile-app/node_modules

[CHART] Execution Summary:
[OK] Successful: 5
[TIME] Total duration: 1.2s
[OK] Cleaned: 5 directories
[FIND] Skipped: 0 (no node_modules found)

When to Use

• Fresh install - Start with a clean slate before npm install
• Dependency issues - Fix corrupted or conflicting dependencies
• Disk space - Free up space by removing unused dependencies
• CI/CD - Ensure clean builds in continuous integration
• Switching branches - Clean up after switching between branches with different dependencies

Tips

• Use filtering to clean specific packages without affecting others
• When filtering, the root node_modules is not removed
• Run your package manager's install command after cleaning
• Combine with other commands in scripts:

{
	"scripts": {
		"reinstall": "wsu clean && npm install",
		"fresh-build": "wsu clean && npm install && wsu build"
	}
}

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!