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 ```bash python3 scripts/validate.py --root . python3 scripts/validate.py --root . --strict ``` ## What Gets Checked ### 1. Bun Version ```bash # 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:** ```json { "name": "my-monorepo", "private": true, "workspaces": ["apps/*", "packages/*"] } ``` **BAD - Dependencies in root:** ```json { "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:** ```json { "dependencies": { "@myorg/ui": "workspace:*", "@myorg/config": "workspace:^1.0.0" } } ``` **BAD - Hardcoded versions:** ```json { "dependencies": { "@myorg/ui": "1.0.0" // BAD: Use workspace:* } } ``` ### 5. Dependency Catalogs (Bun 1.3+) **GOOD - Centralized versions:** ```json // Root package.json { "catalog": { "react": "^19.0.0", "typescript": "^5.7.0", "@types/node": "^22.0.0" } } ``` ```json // 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:** ```json // Don't disable isolation { "workspaces": { "packages": ["apps/*"], "nohoist": ["**"] // Don't do this } } ``` ## Bun 1.3+ Features ### Dependency Catalogs Centralize version management: ```json // Root package.json { "catalog": { "react": "^19.0.0", "next": "^16.0.0", "typescript": "^5.7.0" } } ``` ### Interactive Updates ```bash bun update --interactive # Selectively update deps ``` ### Dependency Chains ```bash bun why react # Explain why a package is installed ``` ### Workspace Commands ```bash # 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:** ```bash bun add <package> --cwd <workspace> ``` ### Issue: Multiple lockfiles **Cause:** Running `bun install` in workspace directory **Fix:** ```bash 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: ```json { "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 ```json "@myorg/shared": "workspace:*" ``` ### 2. Use --cwd for workspace operations ```bash bun add lodash --cwd apps/web # NOT: cd apps/web && bun add ``` ### 3. Single lockfile at root ```bash # Only run bun install from root bun install ``` ### 4. Use catalogs for shared dependencies ```json { "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 ```yaml # .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