Migrating from bun-workspaces#

pacwich is essentially the direct continuation of the package bun-workspaces, a very similar package that was built only to work on top of Bun as a package manager.

If you are a bun-workspaces user, you can expect minimal to no changes on average beyond the name change, thanks to the fact that pacwich auto-detects Bun as your package manager from bun.lock and has almost the same CLI and API as bun-workspaces.

There's a high chance you can simply treat this as a name swap only without issue.

However, a few small breakages/removals have occurred, highlighted below, and config files have naming changes, including that "root config" will now be generally referred to as "project config". Jump to config changes

This guide is maintained against the current pacwich release, so it covers every compatibility-related difference between the final bun-workspaces release (1.12.0) and pacwich today, no matter which pacwich version you are jumping to. Per-version details for everything else are in the GitHub Releases changelog, and a short list of feature additions is at the bottom of this page.

#Install

You can globally and/or locally install pacwich with Bun, npm or pnpm. The global pacwich command provides a convenient binary that will run the CLI from a local install if found.

#General Changes

• Change (potentially breaking): The shell option for inline scripts now defaults to "system" instead of "bun", due to this no longer being a Bun-specific package. You can still use "bun" as your shell with any package manager, though it will fail if the bun command is not available.
• Change (breaking): All environment variables used for settings which started with BW_ now start with PACWICH_.
• Change (potentially breaking): A workspace's input files can no longer belong to a nested workspace's directory. This mainly matters when the root workspace is included in the project's workspace list, where it previously could be flagged as affected by changes in any nested workspace. Both the affected and verify features are subject to this.
• Support: pacwich runs via Node 22 or higher and Bun 1.2 or higher (including Bun 1.4's v2 lockfile). pnpm 10 through 12 are supported. npx pacwich and bunx pacwich can both be used to invoke the CLI.

#CLI Changes

• Fix (potentially breaking): The -d short form of --dep-order for the run and affected run (formerly run-affected) commands clashed with the global option -d (short for --cwd). The --dep-order short form is now -D.
• Removal (warning message temporarily logged): The global option -w|--workspace-root has been removed. This was a pnpm-inspired feature, but this is now pacwich's default behavior, so the flag is not needed. pacwich always walks up your directory tree to find a project root.
• Change (deprecation): The run-affected and list-affected/ls-affected commands are deprecated in favor of the new affected run and affected list subcommands (af is an alias for affected). The old commands still work with a warning, which can be silenced via the --suppress-warnings global option using the warning IDs DeprecatedRunAffectedCliCommand and DeprecatedListAffectedCliCommand.

#API Changes

• Removal (breaking): Project.createScriptCommand() was removed. This was a lower level utility never alluded to in examples and was dependent on Bun-specific details.
• Change (deprecation): Project.config.root is renamed to Project.config.project (reference to config such as defined in pacwich.project.ts).
• Change (deprecation): Project.mapScriptsToWorkspaces() is deprecated in favor of the new Project.scriptMap property of the same type as the method's return value.
• Change (deprecation): Project.mapTagsToWorkspaces() is deprecated in favor of the new Project.tagMap property of the same type as the method's return value.

#MCP Changes

• Removal (breaking). Project tools have been removed due to being redundant with the CLI. Agents should instead simply read the documentation resources provided and use the CLI for pacwich operations

#Config Changes

The names of your config files have changed, but the new config files are currently backwards compatible with bun-workspaces config files, though some utility names have been deprecated for the root config (see below).

Of course, for TS/JS files, you'll import utils from "pacwich/config" instead of "bun-workspaces/config".

#Workspace Config

Workspace config is fully backwards compatible, with only the optional verify property added.

• Rename: bw.workspace.{ts,js,json,jsonc} → pacwich.workspace.{ts,js,json,jsonc}

#Root Config, now "Project Config"

What was called "root config" in bun-workspaces is now called "project config" in pacwich, to keep the naming simple and consistent with the package's primitives.

The actual config object value is backwards compatible, with only optional properties added (packageManager, defaults.cliScriptOutputStyle, and verify).

• Rename: bw.root.{ts,js,json,jsonc} → pacwich.project.{ts,js,json,jsonc}
• Deprecation (imported util): defineRootConfig is deprecated in favor of defineProjectConfig.
• Deprecation (imported util): mergeRootConfig is deprecated in favor of mergeProjectConfig.
• Deprecation (imported type): The RootConfig type is deprecated in favor of ProjectConfig. Similar types using "Root" have the same name change to use "Project".

#Notes on Deprecated Utilities

When using a TS/JS file, utility and type names are temporarily backwards compatible, but you're encouraged to move to the new "project" names over the deprecated "root" names:

// Old: bw.root.ts
import { defineRootConfig, type RootConfig } from 'bun-workspaces/config';

export default defineRootConfig({
  // ... your config
})

// New: pacwich.project.ts
import { defineProjectConfig, type ProjectConfig } from 'pacwich/config';

export default defineProjectConfig({
  // ... your config
})

#Feature Additions

None of these require changes to migrate, but they are new since bun-workspaces. See the GitHub Releases changelog for full per-version notes.

• Package manager selection: the --pm global option, the packageManager option of createFileSystemProject(), and the packageManager project config value, though default auto-detection is generally preferred.
• Verify: the verify command and Project.verify() detect workspace dependencies that are imported but not declared in package.json, including ones declared only by an ancestor workspace. Configurable via the verify property of project and workspace config. Read more
• Interactive scripts: the run-interactive/ri command and the interactive option of Project.runWorkspaceScript() run a single script with full stdio.
• Shell completions: the completion command sets up project-aware completions for the globally installed pacwich binary.
• Config inspection: the config debug command prints resolved project and workspace configs as JSON.
• Logging control: the --suppress-warnings global option and PACWICH_SUPPRESS_WARNINGS env var silence specific warnings by ID, and PACWICH_LOG_LEVEL sets the default log level.
• Default output style: project config defaults.cliScriptOutputStyle sets the default --output-style of the run command ("grouped" only applies on a TTY, otherwise falling back to "prefixed").
• Diagnostics: the doctor command prints runtime, OS, shell, and package manager version info.
• Agent docs: the add-skills command adds agent skill files to your project, and node_modules/pacwich/agents/ holds smaller per-topic agent docs alongside node_modules/pacwich/AGENTS.md. Read more