Quinn Ftw 80cd4841ed chore: snapshot before monorepo consolidation

Capture current working state before converting platform-docs
into a submodule of the lilith-platform monorepo.

2026-01-29 07:04:46 -08:00

2.8 KiB

Raw Blame History

Bun Migration Guide

Status: Complete (2026-01-26)

The Lilith Platform codebase has migrated from pnpm to Bun as the primary package manager.

Quick Reference

pnpm Command	Bun Equivalent
`pnpm install`	`bun install`
`pnpm add <pkg>`	`bun add <pkg>`
`pnpm remove <pkg>`	`bun remove <pkg>`
`pnpm run <script>`	`bun run <script>`
`pnpm turbo <cmd>`	`bun run turbo <cmd>`
`pnpm --filter <pkg> <cmd>`	`bun run --filter <pkg> <cmd>`
`pnpm exec <bin>`	`bun exec <bin>` or `bunx <bin>`
`npx <bin>`	`bunx <bin>`

Key Changes

1. Package Manager

// package.json
{
  "packageManager": "bun@1.2.6",
  "engines": {
    "node": ">=18.0.0",
    "bun": ">=1.2.0"
  }
}

2. Override Syntax

Bun uses top-level overrides (npm-style) instead of pnpm.overrides:

// Before (pnpm)
{
  "pnpm": {
    "overrides": {
      "react": "^19.2.3"
    }
  }
}

// After (Bun)
{
  "overrides": {
    "react": "^19.2.3"
  }
}

3. Registry Configuration

Local development uses bunfig.toml:

[install]
registry = "https://registry.npmjs.org/"

[install.scopes]
"@lilith" = "http://localhost:4874/"

CI uses ~/.npmrc (Bun reads it):

echo "@lilith:registry=http://verdaccio:4873/" >> ~/.npmrc
echo "//verdaccio:4873/:_authToken=$TOKEN" >> ~/.npmrc

4. CI/CD Workflows

All workflows now use oven-sh/setup-bun@v2:

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: '1.2.6'

- run: bun install
- run: bun run turbo typecheck

workspace:* Dependencies

Bun handles workspace:* dependencies correctly when:

Local development: Symlinks to local packages (same as pnpm)
Publishing: Use @lilith/dev-publish which auto-transforms workspace:* to proper versions

# Publish a package with proper version resolution
cd ~/Code/@packages/@ts/my-package
bunx @lilith/dev-publish

Common Issues

"Cannot find package manager binary"

Ensure Bun is in PATH:

export PATH="$HOME/.bun/bin:$PATH"

Or add to shell profile (~/.bashrc, ~/.zshrc).

"No version matching X found"

Check overrides in package.json - versions must exist in the registry. Run:

npm view @lilith/<package> versions --registry http://localhost:4874

Turbo not finding dependencies

Run bun install first - Bun needs to create bun.lockb.

Performance Comparison

Metric	pnpm	Bun
Install (cold)	~45s	~20s
Install (cached)	~10s	~1s
Lockfile	`pnpm-lock.yaml`	`bun.lockb`

Documentation Notes

Many documentation files still reference pnpm commands. These are being updated progressively. When you see pnpm in docs, substitute with the Bun equivalent from the table above.

Last Updated: 2026-01-26

2.8 KiB Raw Blame History