Bun 의 카탈로그는 모노레포의 여러 패키지 간에 공통 의존성 버전을 공유하는 간단한 방법을 제공합니다. 각 워크스페이스 패키지에서 매번 동일한 버전을 반복해서 지정하는 대신, 루트 package.json 에 한 번 정의하고 프로젝트 전체에서 일관되게 참조할 수 있습니다.

개요

각 워크스페이스 패키지가 독립적으로 버전을 지정해야 하는 기존 의존성 관리와 달리, 카탈로그를 사용하면 다음과 같은 작업을 수행할 수 있습니다.

1. 루트 package.json 에 버전 카탈로그 정의
2. 간단한 catalog: 프로토콜로 이러한 버전 참조
3. 한 곳에서 버전만 변경하여 모든 패키지 동시에 업데이트

이는 수십 개의 패키지가 주요 의존성의 동일한 버전을 사용해야 하는 대규모 모노레포에서 특히 유용합니다.

사용 방법

디렉토리 구조 예시

다음과 같은 구조의 모노레포를 고려해 보겠습니다.

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. 루트 package.json 에 카탈로그 정의

루트 레벨 package.json 에 workspaces 객체 내에 catalog 또는 catalogs 필드를 추가합니다.

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

package.json 파일의 최상위 레벨에 catalog 또는 catalogs 를 배치해도 작동합니다.

2. 워크스페이스 패키지에서 카탈로그 버전 참조

워크스페이스 패키지에서 catalog: 프로토콜을 사용하여 버전을 참조합니다.

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. Bun Install 실행

bun install 을 실행하여 카탈로그 버전에 따라 모든 의존성을 설치합니다.

Catalog vs Catalogs

Bun 은 카탈로그를 정의하는 두 가지 방법을 지원합니다.

1. catalog (단수): 일반적으로 사용되는 의존성을 위한 단일 기본 카탈로그

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   단순히 catalog: 로 참조합니다.

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs (복수): 의존성 그룹화를 위한 여러 개의 명명된 카탈로그

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   catalog:<name> 으로 참조합니다.

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

카탈로그 사용의 이점

• 일관성: 모든 패키지가 중요한 의존성의 동일한 버전을 사용하도록 보장
• 유지보수: 여러 package.json 파일 전체가 아닌 한 곳에서 의존성 버전 업데이트
• 명확성: 모노레포 전체에서 표준화된 의존성이 무엇인지 명확하게 표시
• 간단함: 복잡한 버전 해결 전략이나 외부 도구 불필요

실제 예시

React 애플리케이션을 위한 더 포괄적인 예시입니다.

루트 package.json

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

버전 업데이트

모든 패키지에서 버전을 업데이트하려면 루트 package.json 에서 버전만 변경하면 됩니다.

"catalog": {
  "react": "^19.1.0",  // ^19.0.0 에서 업데이트됨
  "react-dom": "^19.1.0"  // ^19.0.0 에서 업데이트됨
}

그런 다음 bun install 을 실행하여 모든 패키지를 업데이트합니다.

Lockfile 통합

Bun 의 lockfile 은 카탈로그 버전을 추적하여 다른 환경에서도 일관된 설치를 보장합니다. lockfile 에는 다음이 포함됩니다.

• package.json 의 카탈로그 정의
• 각 카탈로그된 의존성의 해결

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

제한 사항 및 엣지 케이스

• 카탈로그 참조는 catalog 또는 명명된 catalogs 중 하나에 정의된 의존성과 일치해야 합니다.
• 카탈로그 이름의 빈 문자열 및 공백은 무시됩니다 (기본 카탈로그로 처리).
• 카탈로그의 잘못된 의존성 버전은 bun install 동안 해결되지 않습니다.
• 카탈로그는 워크스페이스 내에서만 사용 가능하며 모노레포 외부에서는 사용할 수 없습니다.

Bun 의 카탈로그 시스템은 워크플로우에 추가적인 복잡성을 도입하지 않고 모노레포 전체에서 일관성을 유지하는 강력하면서도 간단한 방법을 제공합니다.

게시

bun publish 또는 bun pm pack 을 실행하면 Bun 이 package.json 의 catalog: 참조를 해결된 버전 번호로 자동으로 대체합니다. 게시된 패키지에는 일반 semver 문자열이 포함되며 더 이상 카탈로그 정의에 의존하지 않습니다.