Workspaces

utoo supports npm workspaces for monorepo management.

Setup

Define workspaces in your root package.json:


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

Directory Structure


my-monorepo/
├── package.json          # Root with workspaces config
├── packages/
│   ├── ui/
│   │   └── package.json
│   └── utils/
│       └── package.json
└── apps/
    └── web/
        └── package.json

Commands

Target Specific Workspace

Use -w or --workspace to target a specific workspace:

Terminal


# Install in specific workspace
ut install lodash -w packages/ui
 
# Run script in specific workspace
ut run build -w apps/web
 
# Add dev dependency to specific workspace
ut install -D typescript -w packages/utils

Multi-workspace Selection

Use multiple -w flags to select multiple workspaces, with glob pattern support:

Terminal


# Select multiple workspaces
ut run build -w packages/a -w packages/b
 
# Use glob patterns
ut run build -w 'packages/*'

Target All Workspaces

Use --workspaces to target all workspaces:

Terminal


# Run build in all workspaces
ut run build --workspaces
 
# Install in all workspaces
ut install --workspaces

Execution Order

When using --workspaces or multiple -w flags, commands are executed in topological layers:

Packages with no internal dependencies run first
Workspaces in the same layer run concurrently, with output grouped per workspace
Dependents run after their dependencies complete

Example:


▶ 1/3
packages/utils    ✓  (runs first, no deps)
▶ 2/3
packages/ui       ✓  (runs second, depends on utils)
▶ 3/3
apps/web          ✓  (runs last, depends on ui)

Inter-workspace Dependencies

Reference workspace packages using the workspace: protocol:


{
  "name": "apps/web",
  "dependencies": {
    "@my-monorepo/ui": "workspace:*",
    "@my-monorepo/utils": "workspace:^1.0.0"
  }
}

Catalog Protocol

Use the catalog: protocol to centrally manage dependency versions in a monorepo. See Configuration - Catalog.


{
  "dependencies": {
    "react": "catalog:",
    "debug": "catalog:legacy"
  }
}

Interactive Mode

Run ut run without arguments for interactive workspace and script selection:

Terminal


ut run
# → Select workspace: packages/ui
# → Select script: build