KakaFlow KB

Deploy in a Monorepo

5 phút đọc

Deploy in a Monorepo

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

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for configuring and deploying Mastra applications within monorepo structures, covering workspace configurations, build tooling, and troubleshooting for developers using npm, pnpm, yarn, or Turborepo.

Insight

Mastra supports deployment in monorepos with npm workspaces, pnpm workspaces, Yarn workspaces, and Turborepo. Bun workspaces have partial support with known issues. Nx workspaces require package.json files inside workspace packages. The recommended structure places the Mastra application in apps/api with source files in apps/api/src/mastra/ containing agents/, tools/, workflows/, and index.ts subdirectories. Workspace packages are handled automatically: pre-compiled packages use their compiled JavaScript, while uncompiled TypeScript packages are transpiled during the Mastra build. If issues arise with workspace package imports, add the package to the transpilePackages config option in the Mastra bundler configuration. Environment variables must be stored in the application directory (e.g., apps/api/.env) rather than the monorepo root. For cloud deployments, ensure the deploy target points to the application directory (apps/api) not the monorepo root. Use a single lockfile at the monorepo root and align shared library versions to prevent conflicts.

Hành động

To build from a monorepo, run the build command from the correct package using your monorepo tool: npm run build —workspace=apps/api, pnpm —filter api run build, yarn workspace api build, or turbo run build —filter=api. Ensure your package.json build script runs mastra build. For workspace packages, configure transpilePackages in bundler config if needed. Store .env files in the application directory. When deploying to cloud providers, select the application directory as the deploy target.

Kết quả

Mastra applications deploy successfully from monorepo structures with proper workspace configuration and build tooling. Workspace packages are automatically resolved and transpiled as needed.

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

Supports npm workspaces, pnpm workspaces, Yarn workspaces, and Turborepo. Partial support for Bun workspaces with known issues. Nx requires package.json files in 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