Bun Validator

When This Activates

• Setting up a new Bun monorepo
• Before adding dependencies to workspaces
• Auditing existing Bun workspaces
• After AI generates package.json files
• CI/CD pipeline validation

Quick Start

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --strict

What Gets Checked

1. Bun Version

# GOOD: v1.3+
bun --version  # 1.3.0 or higher

# BAD: v1.2 or earlier
bun --version  # 1.2.x

2. Root package.json

GOOD - Monorepo root:

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

BAD - Dependencies in root:

{
  "workspaces": ["apps/*"],
  "dependencies": {
    "react": "^19.0.0"  // BAD: Don't put deps in root
  }
}

3. Workspace Structure

GOOD: See references/full-guide.md (§ Workspace Structure Example) for the full tree — root package.json + bun.lockb, each app/package owns its own package.json.

BAD:

my-monorepo/
├── package.json
├── apps/
│   └── web/
│       ├── package.json
│       └── bun.lockb     # BAD: Lockfile in workspace

4. Workspace Dependencies

GOOD - Using workspace protocol:

{
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/config": "workspace:^1.0.0"
  }
}

BAD - Hardcoded versions:

{
  "dependencies": {
    "@myorg/ui": "1.0.0"  // BAD: Use workspace:*
  }
}

5. Dependency Catalogs (Bun 1.3+)

GOOD - Centralized versions:

// Root package.json
{
  "catalog": {
    "react": "^19.0.0",
    "typescript": "^5.7.0",
    "@types/node": "^22.0.0"
  }
}

// apps/web/package.json
{
  "dependencies": {
    "react": "catalog:"  // Uses version from catalog
  }
}

6. Isolated Installs

GOOD - Default in Bun 1.3: Packages can only access dependencies they explicitly declare.

BAD - Hoisted dependencies:

// Don't disable isolation
{
  "workspaces": {
    "packages": ["apps/*"],
    "nohoist": ["**"]  // Don't do this
  }
}

Bun 1.3+ Features

Dependency Catalogs

See § Dependency Catalogs (Bun 1.3+) above for the catalog syntax.

Interactive Updates

bun update --interactive  # Selectively update deps

Dependency Chains

bun why react  # Explain why a package is installed

Workspace Commands

# Install in specific workspace
bun add express --cwd apps/api

# Run script in workspace
bun run --cwd apps/web dev

# Run in all workspaces
bun run --filter '*' build

Common Issues

Issue: "Cannot find module"

Cause: Dependency not declared in workspace package.json

Fix:

bun add <package> --cwd <workspace>

Issue: Multiple lockfiles

Cause: Running bun install in workspace directory

Fix:

rm apps/*/bun.lockb packages/*/bun.lockb
bun install  # From root only

Issue: Version conflicts

Cause: Same package with different versions across workspaces

Fix: Use dependency catalogs:

{
  "catalog": {
    "problematic-package": "^1.0.0"
  }
}

Validation Output

See references/full-guide.md (§ Validation Output Example) for a sample report.

Best Practices

• Always use the workspace protocol: "@myorg/shared": "workspace:*"
• Use --cwd for workspace operations: bun add lodash --cwd apps/web (not cd apps/web && bun add)
• Run bun install only from the root — keep a single lockfile
• Use dependency catalogs for shared versions (see § Dependency Catalogs above)
• Declare all dependencies explicitly per workspace — don't rely on hoisting

CI/CD Integration

# .github/workflows/validate.yml
- name: Validate Bun Workspace
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

Integration

• linter-formatter-init - Sets up Biome with Bun
• project-init-orchestrator - Creates workspace structure
• nextjs-validator - Validates Next.js in workspace