Deploy in a Monorepo

Deploying Mastra in a monorepo follows the same approach as deploying a standalone application. While some Cloud or Serverless Platform providers may introduce extra requirements, the core setup is the same.

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 monorepo

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

Environment variables

Environment variables like OPENAI_API_KEY should be stored in an .env file at the root of the Mastra application (apps/api), for example:

api/
├── src/
│   └── mastra/
├── .env
├── package.json
└── tsconfig.json

Deployment configuration

The image below shows how to select apps/api as the project root when deploying to Mastra Cloud. While the interface may differ between providers, the configuration remains the same.

info

Make sure the correct package (e.g. apps/api) is selected as the deploy target. Selecting the wrong project root is a common deployment issue in monorepos.

Dependency management

In a monorepo, keep dependencies consistent to avoid version conflicts and build errors.

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