Getting Started#

bun add -g pacwich

# Print help for installing completions
pacwich completion
# Attempt to automatically install completions for your shell
pacwich completion install

# Install to your devDependencies
bun add -d pacwich

# Call the local install
bunx pacwich

Version requirements:
bun: ^1.2.0 | node: >=22.0.0 <=26.x | pnpm: >=10.0.0 <=11.x

Stale workspace data: Note that you need to run your package manager's install for pacwich to have current workspace data available, e.g. via bun install, pnpm install, or npm install. If you've added/removed/updated any workspace package.json, you'll likely need to run this again.

#Terminology

The definitions of workspace and project differ between package managers and monorepo tooling.

In pacwich, the word workspace is closer to how it's used in npm and Bun, a workspace being a nested package in a monorepo. Not necessarily all packages are workspaces, but all workspaces are packages.

The project is synonymous with your root where workspaces are defined, often the root of your git repository as well.

This means you have a root project that has some number of workspaces. The root package is not considered a workspace by default, but it optionally can be.

See: Glossary page

#First commands

If you have a project with workspaces set up and dependencies installed, pacwich works right away. Otherwise, read below on package manager requirements.

Whether using the global install of the CLI pacwich or invoking it with bunx pacwich or npx pacwich, you can run the following commands to get started:

# See usage
pacwich --help

# List workspace data
pacwich ls

# Get JSON metadata
pacwich ls --json

# Run all workspaces' package.json script "my-script" in parallel
pacwich run my-script

# Get help for a specific command
pacwich help run

See more starter code in the CLI Quickstart or TS/JS API Quickstart.

#Using the Verify Command

You can use the verify command just to check for issues with your project. This is especially useful for npm users. Read more here.

Adding the verify command to your root package.json's "prepare" script or as a pre-commit hook can help catch issues with your Project setup and will attempt to detect workspaces that import/export other workspaces' code without declaring them as dependencies:

// your project's root package.json:
{
  "scripts": {
    "prepare": "pacwich verify --strict"
  }
}

#Package Manager Selection

pacwich supports Bun, npm, and pnpm as package managers.

#Auto Detect

pacwich attempts to automatically detect your package manager by looking for a lockfile in the project, such as package-lock.json, pnpm-lock.yaml, or bun.lock.

#When No Lockfile is Found

pacwich requires a lockfile to read workspace data, so you must run your install command to use the package: npm install, pnpm install, or bun install.

#Multiple Lockfiles

If you have multiple lockfiles in your project, such as both bun.lock and pnpm-lock.yaml, pacwich will default automatically in the order of detection: Bun, pnpm, then npm.

#Specify with Config

To explicitly choose a package manager, add pacwich.project.ts to your project root with the following content:

// pacwich.project.ts

import { defineProjectConfig } from "pacwich/config";

export default defineProjectConfig({
  packageManager: "pnpm", // or "bun" or "npm"
});

Note that you can also use a plain JSON file (pacwich.project.json) simply with the content { "packageManager": "bun" } instead.

#Specify with Flag

With the CLI, it's also possible to pass a value to the global --pm flag to explicitly choose a package manager or pass a packageManager option to createFileSystemProject when using the TS API.

#Note: Windows Support

pacwich is primarily supported for POSIX systems (Linux, macOS).

Windows users using cmd.exe are supported. Our CI runs tests in Windows servers to help confirm support for all package managers via Node or Bun. However, stability for cmd.exe is lowest priority.

Windows users are encouraged to use the Windows Subsystem for Linux (WSL) for the best experience, which is generally encouraged for users of Bun and Node anyway.