monorepo でのデプロイ

monorepo での Mastra のデプロイは、スタンドアロンアプリケーションと同じ手順で行います。このガイドでは、monorepo 固有の考慮事項について説明します。基本的なビルドとデプロイの手順については、Mastra サーバーのデプロイを参照してください。

サポートされる monorepo

Mastra は次の環境で動作します。

• npm workspaces
• pnpm workspaces
• Yarn workspaces
• Turborepo

既知の制限事項は次のとおりです。

• Bun workspaces - 部分的にサポートされていますが、既知の問題があります
• 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 からのビルド

monorepo ツールを使用して、適切なパッケージからビルドコマンドを実行します。特別なフラグは必要ありません。

例:

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"
  }
}

Workspace パッケージ

Mastra アプリケーションが他の Workspace パッケージを import する場合、Mastra が自動的に処理します。

• パッケージが事前にコンパイルされている場合（tsc や tsdown でビルドされている場合など）、Mastra はコンパイル済みの JavaScript を import します
• パッケージに未コンパイルの TypeScript が含まれている場合、Mastra はビルド時にトランスパイルします

ほとんどの構成では、設定なしで動作します。Workspace パッケージの import で問題が発生した場合は、そのパッケージを transpilePackages に追加してください。

src/mastra/index.ts

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

bundler は、new Mastra() に渡すオブジェクトの直接のプロパティとして指定してください。サポートされるエントリファイルの構造については、ビルド時の設定を参照してください。

環境変数

.env ファイルは monorepo のルートではなく、Mastra アプリケーションのディレクトリ（apps/api/.env など）に保存してください。

デプロイ設定

クラウド Provider にデプロイする際は、適切なパッケージがデプロイ対象として選択されていることを確認してください。アプリケーションディレクトリ（apps/api など）ではなく monorepo のルートを選択するのは、よくある間違いです。

ほとんどの Provider では、ダッシュボードまたは設定ファイルでルートディレクトリを指定できます。

依存関係の管理

バージョンの競合やビルドエラーを避けるため、依存関係の一貫性を保ってください。

• monorepo のルートに単一の lockfileを置き、すべてのパッケージが同じバージョンを解決するようにする
• Mastra やフレームワークなどの共有ライブラリのバージョンを揃え、重複を防ぐ

トラブルシューティング

Workspace パッケージが見つからない

Mastra が Workspace パッケージを解決できない場合は、次を確認してください。

• パッケージが package.json の依存関係に記載されている
• lockfile が最新である（pnpm install、npm install などを実行済み）
• パッケージに有効な main または exports フィールドがあり、それらが package.json に記載されている

Workspace パッケージに起因する TypeScript エラー

未コンパイルの Workspace パッケージによる型エラーが表示された場合は、次のいずれかを行います。

• 最初にパッケージをビルドする（Mastra のビルドを高速化するには推奨）
• Mastra の設定で、パッケージを transpilePackages に追加する

関連情報

• Mastra サーバーのデプロイ: 基本的なビルドとデプロイのガイド
• 設定リファレンス: bundler.transpilePackages などのオプション
• CLI リファレンス: ビルドコマンドのフラグ