bun-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bun Validator

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

验证Bun工作区配置，预防常见的monorepo问题。确保遵循Bun 1.3+的模式以及正确的工作区隔离。

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

搭建新的Bun monorepo
向工作区添加依赖之前
审计现有Bun工作区
AI生成package.json文件之后
CI/CD流水线验证

Quick Start

快速开始

bash

python3 ~/.claude/skills/bun-validator/scripts/validate.py --root .
python3 ~/.claude/skills/bun-validator/scripts/validate.py --root . --strict

bash

python3 ~/.claude/skills/bun-validator/scripts/validate.py --root .
python3 ~/.claude/skills/bun-validator/scripts/validate.py --root . --strict

What Gets Checked

检查内容

1. Bun Version

1. Bun版本

bash

undefined

bash

undefined

GOOD: v1.3+

正确：v1.3+

bun --version # 1.3.0 or higher

bun --version # 1.3.0或更高版本

BAD: v1.2 or earlier

错误：v1.2或更早版本

bun --version # 1.2.x

undefined

bun --version # 1.2.x

undefined

2. Root package.json

2. 根目录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
  }
}

正确的Monorepo根目录配置：

json

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

错误的配置：根目录存在依赖

json

{
  "workspaces": ["apps/*"],
  "dependencies": {
    "react": "^19.0.0"  // 错误：不要在根目录放置依赖
  }
}

3. Workspace Structure

3. 工作区结构

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

正确结构：

my-monorepo/
├── package.json          # 根目录包含workspaces配置，private: true
├── bun.lockb             # 仅在根目录存在单个锁定文件
├── apps/
│   ├── web/
│   │   └── package.json  # 拥有独立依赖
│   └── api/
│       └── package.json  # 拥有独立依赖
└── packages/
    ├── ui/
    │   └── package.json  # 共享包
    └── config/
        └── package.json  # 共享配置

错误结构：

my-monorepo/
├── package.json
├── apps/
│   └── web/
│       ├── package.json
│       └── bun.lockb     # 错误：锁定文件不应出现在工作区内

4. Workspace Dependencies

4. 工作区依赖

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:*
  }
}

正确：使用workspace协议

json

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

错误：硬编码版本号

json

{
  "dependencies": {
    "@myorg/ui": "1.0.0"  // 错误：应使用workspace:*
  }
}

5. Dependency Catalogs (Bun 1.3+)

5. 依赖目录（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
  }
}

正确：集中化版本管理

json

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

json

// apps/web/package.json
{
  "dependencies": {
    "react": "catalog:"  // 使用目录中定义的版本
  }
}

6. Isolated Installs

6. 隔离安装

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默认行为

包只能访问其显式声明的依赖。

错误：依赖被提升

json

// 不要禁用隔离
{
  "workspaces": {
    "packages": ["apps/*"],
    "nohoist": ["**"]  // 不要这样做
  }
}

Bun 1.3+ Features

Bun 1.3+特性

Dependency Catalogs

依赖目录

Centralize version management:

json

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

集中化版本管理：

json

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

Interactive Updates

交互式更新

bash

bun update --interactive  # Selectively update deps

bash

bun update --interactive  # 选择性更新依赖

Dependency Chains

依赖链

bash

bun why react  # Explain why a package is installed

bash

bun why react  # 解释某个包被安装的原因

Workspace Commands

工作区命令

bash

undefined

bash

undefined

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

undefined

bun run --filter '*' build

undefined

Common Issues

常见问题

Issue: "Cannot find module"

问题："Cannot find module"

Cause: Dependency not declared in workspace package.json

Fix:

bash

bun add <package> --cwd <workspace>

原因： 工作区的package.json中未声明该依赖

修复方法：

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

原因： 在工作区目录中运行了

bun install

修复方法：

bash

rm apps/*/bun.lockb packages/*/bun.lockb
bun install  # 仅在根目录运行

Issue: Version conflicts

问题：版本冲突

Cause: Same package with different versions across workspaces

Fix: Use dependency catalogs:

json

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

原因： 不同工作区中同一包使用了不同版本

修复方法： 使用依赖目录

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

=== Bun工作区验证报告 ===

Bun版本：1.3.2 ✓

根目录package.json：
  ✓ private: true
  ✓ 已定义workspaces
  ✗ 根目录存在依赖（应为空）

工作区结构：
  ✓ apps/web - 有效工作区
  ✓ apps/api - 有效工作区
  ✓ packages/ui - 有效工作区
  ✗ apps/web/bun.lockb - 锁定文件应仅存在于根目录

依赖配置：
  ✓ 使用了workspace:*协议
  ✗ @myorg/ui使用了硬编码版本"1.0.0"

依赖目录：
  ✗ 未找到依赖目录（Bun 1.3+推荐使用）

总结：发现3个问题

Best Practices

最佳实践

1. Always use workspace protocol

1. 始终使用workspace协议

json

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

json

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

2. Use --cwd for workspace operations

2. 使用--cwd参数执行工作区操作

bash

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

bash

bun add lodash --cwd apps/web  # 不要这样做：cd apps/web && bun add

3. Single lockfile at root

3. 仅在根目录保留单个锁定文件

bash

undefined

bash

undefined

Only run bun install from root

仅在根目录运行bun install

bun install

undefined

bun install

undefined

4. Use catalogs for shared dependencies

4. 使用依赖目录管理共享依赖

json

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

json

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

5. Declare all dependencies explicitly

5. 显式声明所有依赖

Each workspace should list all its dependencies - don't rely on hoisting.

每个工作区都应列出其所有依赖 - 不要依赖依赖提升。

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

.github/workflows/validate.yml

name: Validate Bun Workspace run: | python3 ~/.claude/skills/bun-validator/scripts/validate.py
--root .
--strict
--ci

undefined

name: Validate Bun Workspace run: | python3 ~/.claude/skills/bun-validator/scripts/validate.py
--root .
--strict
--ci

undefined

Integration

集成能力

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

```
linter-formatter-init
```
- 搭配Bun设置Biome
```
project-scaffold
```
- 创建工作区结构
```
nextjs-validator
```
- 验证工作区中的Next.js配置