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

You can also browse some of the feature additions below.

#Agent Assistance

You can have an LLM agent assist with migration by simply instructing it to read this page as https://pacwich.dev/intro/bun-workspaces-migration/index.md.

---

#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_.
• Support: pacwich runs via Node 22 or higher and Bun 1.2 or higher. npx pacwich and bunx pacwich can both be used to invoke the CLI.
• Addition: Along with node_modules/pacwich/AGENTS.md, you can access smaller agent files for more specific usage docs under node_modules/pacwich/agents/. Read more

#CLI Changes

• Fix (possibly breaking): The run and run-affected -d option (short for --dep-order) 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.
• Addition: A new global option --pm to explicitly set a package manager, though default auto-detection or using project config is generally preferred.
• Addition: Project config can now set defaults.cliScriptOutputStyle to set the default --output-style of the run command, "grouped" only available on a TTY, which falls back to "prefixed".
• Addition: A CLI command add-skills to add agent skill files to your project
• Addition: A verify command for the new verify feature described above.

#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.
• Addition: createFileSystemProject() accepts a packageManager option, similar to the new --pm CLI option, though default auto-detection or using project config is generally preferred.
• Addition: Project.verify() is the API equivalent of the new CLI verify command.

#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.

• 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.

• 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".
• Addition (config value): The packageManager value sets the expected package manager, mainly for when multiple lockfiles are present
• Addition (config value): defaults.cliScriptOutputStyle sets the default --output-style argument for running scripts
• Addition (config value):: New verify property sets options for the verify feature

#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
})