Bun monorepo workflows (Cloudflare Workers SaaS kit)

This repo is currently pnpm-based, but Bun can act as the package manager for the monorepo. This skill covers (1) day-to-day Bun equivalents for pnpm workflows and (2) a safe pnpm → Bun migration checklist.

Quick commands (Bun)

• •Install all deps: bun install
• •CI install (frozen lockfile): bun ci (equivalent to bun install --frozen-lockfile)
• •Run a root script: bun run <script>
• •Run a workspace script (common patterns):
  • •By filter: bun --filter <workspace-name-or-glob> run <script>
  • •By path filter: bun --filter ./apps/user-application run build
• •Add deps:
  • •Prod: bun add <pkg>
  • •Dev: bun add -d <pkg>
• •List deps: bun pm ls (or bun list)
• •Lockfile / migration utilities: bun pm migrate

Filtering and “package scoping”

Bun’s primary mechanism is --filter.

Examples:

• •Install everything except one workspace: bun install --filter '!data-service'
• •Install only one workspace (by path): bun install --filter './apps/user-application'
• •Run TS typecheck in just UI: bun --filter @workspace/ui run tsc

Notes:

• •Bun supports workspace globs and negative patterns.
• •Prefer filtering by path when package names aren’t unique or you’re unsure of the workspace name.

Cloudflare/Wrangler note (important)

This repo uses Cloudflare Workers tooling (Wrangler, workerd). Bun is fine as a package manager, but Wrangler is not universally supported when executed via Bun’s runtime.

Practical guidance:

• •Prefer bun run <script> without forcing Bun’s runtime.
• •Bun’s bun run respects #!/usr/bin/env node shebangs by default, so CLIs like wrangler usually run on your system Node.
• •If you hit Wrangler weirdness under Bun, run Wrangler directly with Node (or via the existing pnpm workflow) rather than forcing bun --bun.

pnpm → Bun migration checklist (safe)

Bun will automatically migrate pnpm-lock.yaml to bun.lock when you run bun install and no bun.lock exists yet.

Recommended sequence:

1. •Clean install state
   • •Remove node_modules (and workspace node_modules if present).
2. •Generate Bun lockfile
   • •Run bun install at repo root.
   • •Verify it produced bun.lock.
3. •Verify key workflows still work
   • •Run the same “known good” scripts you currently use for CI/dev (build + typecheck for each app/package).
   • •Pay special attention to:
     • •packages/data-ops build
     • •app typechecks
     • •Wrangler/dev scripts
4. •Commit lockfile + any required config changes
   • •Bun docs recommend committing bun.lock.
5. •Optional: remove pnpm artifacts after verification
   • •After you’re confident, remove pnpm-lock.yaml and pnpm-workspace.yaml.
   • •If you keep pnpm around temporarily, do not mix installs (avoid generating both lockfiles in CI).

Bun-specific notes that matter during migration:

• •Bun v1.2+ defaults to the text lockfile bun.lock (older versions used bun.lockb).
• •Bun does not run dependency lifecycle scripts by default; if a dependency requires scripts, add it to trustedDependencies in the relevant package.json, then reinstall.

What to update in repo configs (typical)

When the actual migration happens (if/when you switch the repo’s canonical PM):

• •Root package.json:
  • •Consider setting packageManager to bun@<version> to signal the expected tool.
  • •Ensure workspaces config exists (Bun supports workspaces and will migrate from pnpm-workspace.yaml automatically).
• •CI:
  • •Replace pnpm install with bun ci.
  • •Use oven-sh/setup-bun GitHub Action.

References

• •Command mapping + “pnpm filter” equivalents: see .github/skills/bun-monorepo-workflows/references/command-mapping.md
• •Migration gotchas + verification checklist: see .github/skills/bun-monorepo-workflows/references/migration-notes.md