KakaFlow KB

Triển khai Mastra trong Monorepo

5 phút đọc

Triển khai Mastra trong Monorepo

Trust: ★★★☆☆ (0.90) · 0 validations · factual

Published: 2026-05-09 · Source: crawler_authoritative

Tình huống

Nhà phát triển cần triển khai ứng dụng Mastra (AI agent framework) trong cấu trúc monorepo với nhiều workspace packages

Insight

Mastra hỗ trợ triển khai trong monorepo với các công cụ: npm workspaces, pnpm workspaces, Yarn workspaces, và Turborepo. Bun workspaces chỉ được hỗ trợ một phần với các known issues. Nx cần có package.json bên trong các workspace packages. Cấu trúc ví dụ đặt ứng dụng Mastra tại apps/api với các thư mục agents, tools, workflows. Khi ứng dụng import từ workspace packages khác, Mastra tự động xử lý: nếu package đã được compile (tsc, tsdown) thì import JS đã compile; nếu là TypeScript chưa compile thì Mastra transpile trong quá trình build. Lưu .env files trong thư mục ứng dụng (apps/api/.env) chứ không phải monorepo root. Khi deploy lên cloud providers, phải chọn đúng package làm deploy target (apps/api) chứ không phải monorepo root.

Hành động

Build commands cho từng package manager: npm run build —workspace=apps/api; pnpm —filter api run build; yarn workspace api build; turbo run build —filter=api. Package.json script cần chạy ‘mastra build’. Nếu gặp vấn đề với workspace package imports, thêm package vào transpilePackages trong mastra config. Troubleshooting: Đảm bảo package được liệt kê trong dependencies, lockfile cập nhật, có valid main/exports field. Nếu có TypeScript errors từ uncompiled packages, build package trước hoặc thêm vào transpilePackages. Dependency management: dùng single lockfile ở root và align versions của shared libraries.

Điều kiện áp dụng

Áp dụng khi triển khai ứng dụng Mastra trong monorepo. Bun workspaces có hỗ trợ giới hạn. Nx yêu cầu có package.json trong workspace packages.

Nội dung gốc (Original)

Deploy in a monorepo

Deploying Mastra in a monorepo follows the same process as a standalone application. This guide covers monorepo-specific considerations. For the core build and deployment steps, see Deploy a Mastra Server.

Supported monorepos

Mastra works with:

  • npm workspaces
  • pnpm workspaces
  • Yarn workspaces
  • Turborepo

Known limitations:

  • Bun workspaces - partial support; known issues
  • Nx - You can use Nx’s supported dependency strategies but you need to have package.json files inside your workspace packages

Example structure

In this example, the Mastra application is located at apps/api:

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

Building from a monorepo

Use your monorepo tool to run the build command from the correct package. There’s no need for special flags.

Examples:

npm:

npm run build --workspace=apps/api

pnpm:

pnpm --filter api run build

yarn:

yarn workspace api build

Turborepo:

turbo run build --filter=api

Your package’s build script should run mastra build:

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

Workspace packages

When your Mastra application imports from other workspace packages, Mastra handles this automatically:

  • If the package is pre-compiled (e.g., built with tsc or tsdown), Mastra imports the compiled JavaScript
  • If the package contains uncompiled TypeScript, Mastra transpiles it during the build

For most setups, this works without configuration. If you encounter issues with workspace package imports, add the package to transpilePackages:

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

Environment variables

Store .env files in the Mastra application directory (e.g., apps/api/.env), not the monorepo root.

Deployment configuration

When deploying to cloud providers, ensure the correct package is selected as the deploy target. Selecting the monorepo root instead of the application directory (e.g., apps/api) is a common mistake.

Most providers let you specify the root directory in their dashboard or configuration file.

Dependency management

Keep dependencies consistent to avoid version conflicts and build errors:

  • Use a single lockfile at the monorepo root so all packages resolve the same versions
  • Align versions of shared libraries (like Mastra or frameworks) to prevent duplicates

Troubleshooting

Workspace package not found

If Mastra can’t resolve a workspace package, ensure:

  • The package is listed in your package.json dependencies
  • Your lockfile is up to date (pnpm install, npm install, etc.)
  • The package has a valid main or exports field in its package.json

TypeScript errors from workspace packages

If you see type errors from uncompiled workspace packages, either:

  • Build the package first (recommended for faster Mastra builds)
  • Add the package to transpilePackages in your Mastra config

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược