> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# monorepo でのデプロイ

monorepo での Mastra のデプロイは、スタンドアロンアプリケーションと同じ手順で行います。このガイドでは、monorepo 固有の考慮事項について説明します。基本的なビルドとデプロイの手順については、[Mastra サーバーのデプロイ](https://mastra.zisheng.pro/ja/docs/deployment/mastra-server)を参照してください。

## サポートされる monorepo

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

- npm workspaces
- pnpm workspaces
- Yarn workspaces
- Turborepo

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

- Bun workspaces - 部分的にサポートされていますが、既知の問題があります
- Nx - Nx の[サポート対象の依存関係戦略](https://nx.dev/concepts/decisions/dependency-management)を使用できますが、Workspace パッケージ内に `package.json` ファイルが必要です

## 構成例

この例では、Mastra アプリケーションは `apps/api` にあります。

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

## monorepo からのビルド

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

例:

**npm**:

```bash
npm run build --workspace=apps/api
```

**pnpm**:

```bash
pnpm --filter api run build
```

**yarn**:

```bash
yarn workspace api build
```

**Turborepo**:

```bash
turbo run build --filter=api
```

パッケージの `build` スクリプトでは、`mastra build` を実行する必要があります。

```json
{
  "scripts": {
    "build": "mastra build"
  }
}
```

## Workspace パッケージ

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

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

ほとんどの構成では、設定なしで動作します。Workspace パッケージの import で問題が発生した場合は、そのパッケージを [`transpilePackages`](https://mastra.zisheng.pro/ja/reference/configuration) に追加してください。

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

`bundler` は、`new Mastra()` に渡すオブジェクトの直接のプロパティとして指定してください。サポートされるエントリファイルの構造については、[ビルド時の設定](https://mastra.zisheng.pro/ja/docs/deployment/mastra-server)を参照してください。

## 環境変数

`.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`](https://mastra.zisheng.pro/ja/reference/configuration) に追加する

## 関連情報

- [Mastra サーバーのデプロイ](https://mastra.zisheng.pro/ja/docs/deployment/mastra-server): 基本的なビルドとデプロイのガイド
- [設定リファレンス](https://mastra.zisheng.pro/ja/reference/configuration): `bundler.transpilePackages` などのオプション
- [CLI リファレンス](https://mastra.zisheng.pro/ja/reference/cli/mastra): ビルドコマンドのフラグ