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