모노레포에 배포

모노레포에 Mastra를 배포하는 과정은 독립 실행형 애플리케이션과 동일합니다. 이 가이드에서는 모노레포 관련 고려 사항을 다룹니다. 핵심 빌드 및 배포 단계는 Mastra 서버 배포를 참조하세요.

지원되는 단일 저장소

Mastra는 다음과 함께 작동합니다.

• npm 작업공간
• pnpm 작업공간
• 원사 작업 공간
• 터보레포

알려진 제한사항:

• Bun Workspace - 부분 지원, 알려진 문제 있음
• Nx - Nx의 지원되는 종속성 전략을 사용할 수 있지만 Workspace 패키지 내부에 package.json 파일이 있어야 함

예시 구조

이 예에서 Mastra 애플리케이션은 다음 위치에 있습니다.apps/api:

apps/
├── api/
│   ├── src/
│   │   └── mastra/
│   │       ├── agents/
│   │       ├── tools/
│   │       ├── workflows/
│   │       └── index.ts
│   ├── package.json
│   └── tsconfig.json
└── web/
packages/
├── ui/
└── utils/
package.json

모노레포에서 빌드하기

monorepo Tool을 사용하여 올바른 패키지에서 빌드 명령을 실행하세요. 특별한 플래그가 필요하지 않습니다.

예:

npm

npm run build --workspace=apps/api

pnpm

pnpm --filter api run build

yarn

yarn workspace api build

Turborepo

turbo run build --filter=api

패키지의 build 스크립트는 mastra build를 실행해야 합니다.

apps/api/package.json

{
  "scripts": {
    "build": "mastra build"
  }
}

작업 공간 패키지

Mastra 애플리케이션이 다른 작업 공간 패키지에서 가져올 때 Mastra는 이를 자동으로 처리합니다.

• 패키지가 미리 컴파일된 경우(예: tsc 또는 tsdown) Mastra는 컴파일된 JavaScript를 가져옵니다.
• 패키지에 컴파일되지 않은 TypeScript가 포함되어 있으면 Mastra는 빌드 중에 이를 트랜스파일합니다. 대부분의 설정에서는 구성 없이도 작동합니다. 작업공간 패키지 가져오기에 문제가 발생하는 경우 해당 패키지를 다음에 추가하세요.transpilePackages:

src/mastra/index.ts

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/utils'],
  },
})

new Mastra()에 전달하는 객체의 직접 속성으로 bundler를 유지하세요. 지원되는 진입점 파일 형태는 빌드 시간 구성을 참조하세요.

환경변수

.env 파일은 모노레포 루트가 아닌 Mastra 애플리케이션 디렉터리(예: apps/api/.env)에 저장하세요.

배포 구성

클라우드 Provider에 배포할 때 배포 대상으로 올바른 패키지를 선택했는지 확인하세요. 애플리케이션 디렉터리(예: apps/api) 대신 모노레포 루트를 선택하는 것은 흔한 실수입니다. 대부분의 공급자는 대시보드 또는 구성 파일에서 루트 디렉터리를 지정할 수 있습니다.

종속성 관리

버전 충돌 및 빌드 오류를 방지하려면 종속성을 일관되게 유지하세요.

• 모든 패키지가 동일한 버전을 확인하도록 모노레포 루트에서 single lockfile 사용
• 중복을 방지하도록 Mastra 또는 프레임워크 같은 shared libraries의 버전 정렬

문제 해결

Workspace 패키지를 찾을 수 없습니다.

Mastra가 작업 공간 패키지를 확인할 수 없는 경우 다음을 확인하세요.

• 패키지가 package.json의 종속성에 나열되어 있는지 확인합니다.
• 잠금 파일이 최신 상태인지 확인합니다(pnpm install, npm install 등).
• 패키지의 package.json에 유효한 main 또는 exports 필드가 있는지 확인합니다.

작업 공간 패키지의 TypeScript 오류

컴파일되지 않은 작업 영역 패키지에서 유형 오류가 표시되면 다음 중 하나를 수행하세요.

• 패키지를 먼저 빌드하세요(더 빠른 Mastra 빌드를 위해 권장).
• Mastra 구성의 transpilePackages에 패키지를 추가하세요.

관련된

• Mastra 서버 배포: 핵심 빌드 및 배포 가이드
• 구성 레퍼런스: bundler.transpilePackages 및 기타 옵션
• CLI 레퍼런스: 빌드 명령 플래그