# 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](https://mastra.ai/docs/deployment/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](https://nx.dev/concepts/decisions/dependency-management) 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`:

```text
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**:

```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
```

Your package's `build` script should run `mastra build`:

```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`](https://mastra.ai/reference/configuration):

```typescript
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`](https://mastra.ai/reference/configuration) in your Mastra config

## Related

- [Deploy a Mastra Server](https://mastra.ai/docs/deployment/mastra-server): Core build and deployment guide
- [Configuration Reference](https://mastra.ai/reference/configuration): `bundler.transpilePackages` and other options
- [CLI Reference](https://mastra.ai/reference/cli/mastra): Build command flags