bun-validator

Bun Validator

Validates Bun workspace configuration and prevents common monorepo issues. Ensures Bun 1.3+ patterns and proper workspace isolation.

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:

my-monorepo/
├── package.json          # Root with workspaces, private: true
├── bun.lockb             # Single lockfile at root
├── apps/
│   ├── web/
│   │   └── package.json  # Own dependencies
│   └── api/
│       └── package.json  # Own dependencies
└── packages/
    ├── ui/
    │   └── package.json  # Shared package
    └── config/
        └── package.json  # Shared config

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

Centralize version management:

// Root package.json
{
  "catalog": {
    "react": "^19.0.0",
    "next": "^16.0.0",
    "typescript": "^5.7.0"
  }
}

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

=== Bun Workspace Validation Report ===

Bun Version: 1.3.2 ✓

Root package.json:
  ✓ private: true
  ✓ workspaces defined
  ✗ Found dependencies in root (should be empty)

Workspace Structure:
  ✓ apps/web - valid workspace
  ✓ apps/api - valid workspace
  ✓ packages/ui - valid workspace
  ✗ apps/web/bun.lockb - lockfile should only be at root

Dependencies:
  ✓ Using workspace:* protocol
  ✗ @myorg/ui uses hardcoded version "1.0.0"

Catalogs:
  ✗ No dependency catalog found (recommended for Bun 1.3+)

Summary: 3 issues found

Best Practices

1. Always use workspace protocol

"@myorg/shared": "workspace:*"

2. Use --cwd for workspace operations

bun add lodash --cwd apps/web  # NOT: cd apps/web && bun add

3. Single lockfile at root

# Only run bun install from root
bun install

4. Use catalogs for shared dependencies

{
  "catalog": {
    "typescript": "^5.7.0",
    "vitest": "^3.0.0"
  }
}

5. Declare all dependencies explicitly

Each workspace should list all its dependencies - 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