bun-validator

Bun バリデーター

このツールが有効になるタイミング

• 新しい Bun モノレポをセットアップするとき
• ワークスペースに依存関係を追加する前
• 既存の Bun ワークスペースを監査するとき
• AI が package.json ファイルを生成した後
• CI/CD パイプラインの検証時

クイックスタート

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

チェック項目

1. Bun のバージョン

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

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

2. ルートの package.json

GOOD - モノレポのルート：

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

BAD - ルートに依存関係がある場合：

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

3. ワークスペースの構造

GOOD： 完全なツリーについては、references/full-guide.md（§ ワークスペース構造の例）を参照してください。ルートには package.json と bun.lockb があり、各アプリ／パッケージがそれぞれ独自の package.json を持ちます。

BAD：

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

4. ワークスペースの依存関係

GOOD - workspace プロトコルの使用：

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

BAD - バージョンのハードコード：

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

5. 依存関係カタログ（Bun 1.3+）

GOOD - バージョンの一元管理：

// 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. 分離インストール

GOOD - Bun 1.3 のデフォルト： パッケージがアクセスできるのは、明示的に宣言した依存関係のみです。

BAD - 依存関係のホイスト：

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

Bun 1.3+ の機能

依存関係カタログ

カタログの構文については、上記の「§ 依存関係カタログ（Bun 1.3+）」を参照してください。

インタラクティブな更新

bun update --interactive  # Selectively update deps

依存関係チェーン

bun why react  # Explain why a package is installed

ワークスペースコマンド

# 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

よくある問題

問題：「Cannot find module」

原因： ワークスペースの package.json に依存関係が宣言されていません。

解決方法：

bun add <package> --cwd <workspace>

問題：ロックファイルが複数ある

原因： ワークスペースのディレクトリ内で bun install を実行しています。

解決方法：

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

問題：バージョンの競合

原因： ワークスペース間で同じパッケージに異なるバージョンが指定されています。

解決方法： 依存関係カタログを使用します。

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

検証結果

レポートのサンプルについては、references/full-guide.md（§ 検証結果の例）を参照してください。

ベストプラクティス

• 常に workspace プロトコルを使用します："@myorg/shared": "workspace:*"
• ワークスペースの操作には --cwd を使用します：bun add lodash --cwd apps/web（cd apps/web && bun add ではなく）
• bun install はルートからのみ実行し、ロックファイルは 1 つに保ちます
• 共通バージョンには依存関係カタログを使用します（上記の「§ 依存関係カタログ」を参照）
• すべての依存関係をワークスペースごとに明示的に宣言し、ホイストに依存しないようにします

CI/CD との統合

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

統合

• linter-formatter-init - Bun で Biome をセットアップします
• project-init-orchestrator - ワークスペース構造を作成します
• nextjs-validator - ワークスペース内の Next.js を検証します