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:

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