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:

apps/api/package.json

{
  "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:

src/mastra/index.ts

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.

Mastra Cloud

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.

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

Related

• Deploy a Mastra Server - Core build and deployment guide
• Configuration Reference - bundler.transpilePackages and other options
• CLI Reference - Build command flags