@mastra/deployer 1.0.0-beta.21 → 1.0.0-beta.23

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.23",
   "package": "@mastra/deployer",
   "exports": {
     "Deps": {

package/dist/docs/deployment/01-overview.md

@@ -19,7 +19,7 @@ Mastra can run against any of these runtime environments:
 
 Mastra provides a [server](https://mastra.ai/docs/v1/server/mastra-server) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
 
-Visit the [Mastra server deployment guide](https://mastra.ai/docs/v1/deployment/mastra-server).
+Use this option when you need full control over your infrastructure, long-running processes, or WebSocket connections. The [Mastra server deployment guide](https://mastra.ai/docs/v1/deployment/mastra-server) provides more details.
 
 ### Monorepo
 
@@ -31,6 +31,8 @@ Read about [monorepo deployment](https://mastra.ai/docs/v1/deployment/monorepo).
 
 Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the build and deployment process.
 
+Use this option for auto-scaling, minimal infrastructure management, or when you're already using one of these platforms.
+
 - [Amazon EC2](https://mastra.ai/guides/v1/deployment/amazon-ec2)
 - [AWS Lambda](https://mastra.ai/guides/v1/deployment/aws-lambda)
 - [Azure App Services](https://mastra.ai/guides/v1/deployment/azure-app-services)
@@ -41,7 +43,9 @@ Mastra applications can be deployed to cloud providers and serverless platforms.
 
 ### Web Framework
 
-When Mastra is integrated with a web framework, it deploys alongside your application using the framework's standard deployment process. The guides below cover framework-specific configuration requirements for deployment:
+When Mastra is integrated with a web framework, it deploys alongside your application using the framework's standard deployment process. The guides below cover framework-specific configuration requirements for deployment.
+
+Use these guides when adding Mastra to an existing Next.js or Astro application.
 
 - [With Next.js on Vercel](https://mastra.ai/docs/v1/deployment/web-framework#with-nextjs-on-vercel)
 - [With Astro on Vercel](https://mastra.ai/docs/v1/deployment/web-framework#with-astro-on-vercel)

package/dist/docs/deployment/02-mastra-server.md

@@ -1,70 +1,129 @@
-> Learn how to build a Mastra server with build settings and deployment options.
+> Learn how to build and deploy a Mastra server.
 
 # Deploy a Mastra Server
 
-Mastra runs as a standard Node.js server and can be deployed across a wide range of environments.
+Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.
 
-## Default project structure
+> **Note:**
 
-The [getting started guide](https://mastra.ai/guides/v1/getting-started/quickstart) scaffolds a project with sensible defaults to help you begin quickly. By default, the CLI organizes application files under the `src/mastra/` directory, resulting in a structure similar to the following:
+This guide covers deploying the standalone server generated by `mastra build`. If you need to integrate Mastra into an existing Express or Hono application, see [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters) instead.
+
+## Building your application
+
+Run the build command from your project root:
+
+```bash
+mastra build
+```
+
+This creates a `.mastra` directory containing your production-ready server.
+
+> **Note:**
+
+Read the [`mastra build`](https://mastra.ai/reference/v1/cli/mastra#mastra-build) reference for all available flags.
+
+## Build output
+
+After building, Mastra creates the following structure:
 
 ```
-src/
-└── mastra/
-    ├── agents/
-    ├── tools/
-    ├── workflows/
-    └── index.ts
-package.json
-tsconfig.json
+.mastra/
+├── .build/                # Intermediate build artifacts (module maps, analysis)
+└── output/
+    ├── index.mjs          # Server entry point
+    ├── mastra.mjs         # Your bundled Mastra configuration
+    ├── tools.mjs          # Aggregated tool exports
+    ├── tools/             # Individual tool bundles
+    ├── package.json       # Production dependencies
+    ├── node_modules/      # Installed dependencies
+    ├── .npmrc             # Copied from your project (if present)
+    ├── public/            # Static assets (if src/mastra/public exists)
+    └── playground/        # Studio UI (if --studio flag used)
 ```
 
-## Building
+The `output` directory is self-contained. You can copy it to any server and run it directly.
+
+## Running the server
 
-The `mastra build` command starts the build process:
+Start the server using the Mastra CLI:
 
 ```bash
-mastra build
+mastra start
 ```
 
-### Customizing the input directory
-
-If your Mastra files are located elsewhere, use the `--dir` flag to specify the custom location. The `--dir` flag tells Mastra where to find your entry point file (`index.ts` or `index.js`) and related directories.
+Or run directly with Node.js:
 
 ```bash
-mastra build --dir ./my-project/mastra
+node .mastra/output/index.mjs
 ```
 
+The `mastra start` command provides additional features:
+- Loads environment variables from `.env.production` and `.env`
+- Provides helpful error messages for missing modules
+- Handles process signals for graceful shutdown
+
+> **Note:**
+
+Read the [`mastra start`](https://mastra.ai/reference/v1/cli/mastra#mastra-start) reference for all available flags.
+
+## Build configuration
+
+### Public folder
+
+If a `public` folder exists in your Mastra directory (`src/mastra/public`), its contents are copied to the output directory during build. These files are served as static assets by the server.
+
+### Mastra configuration
+
+The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/v1/server/mastra-server). For all available options, see the [configuration reference](https://mastra.ai/reference/v1/configuration).
+
 ## Build process
 
-The build process follows these steps:
+The build follows these steps:
 
-1. **Locates entry file**: Finds `index.ts` or `index.js` in your specified directory (default: `src/mastra/`).
-2. **Creates build directory**: Generates a `.mastra/` directory containing:
-   - **`.build`**: Contains dependency analysis, bundled dependencies, and build configuration files.
-   - **`output`**: Contains the production-ready application bundle with `index.mjs` and project-specific files.
-3. **Copies static assets**: Copies the `public/` folder contents to the `output` directory for serving static files.
-4. **Bundles code**: Uses Rollup with tree shaking and source maps for optimization.
-5. **Generates server**: Creates a [Hono](https://hono.dev) HTTP server ready for deployment.
+1. **Locates entry file**: Finds `index.ts` or `index.js` in your Mastra directory.
+2. **Discovers tools**: Scans for tool files matching `{mastraDir}/tools/**/*.{js,ts}`, excluding test files.
+3. **Analyzes dependencies**: Determines which packages to bundle vs. install externally.
+4. **Bundles code**: Uses Rollup with tree-shaking and optional source maps.
+5. **Generates server**: Creates a Hono-based HTTP server as `index.mjs`.
+6. **Installs dependencies**: Runs `npm install` in the output directory.
+7. **Copies assets**: Copies `public` folder and `.npmrc` if present.
 
-### Build output structure
+## Environment variables
 
-After building, Mastra creates a `.mastra/` directory with the following structure:
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Server port (default: `4111`) |
+| `MASTRA_STUDIO_PATH` | Path to Studio build directory (default: `./playground`) |
+| `MASTRA_SKIP_DOTENV` | Skip loading `.env` files when set |
+| `NODE_OPTIONS` | Node.js options (e.g., `--max-old-space-size=4096` for build memory issues) |
 
-```
-.mastra/
-├── .build/
-└── output/
-```
+## Server endpoints
+
+The built server exposes endpoints for health checks, agents, workflows, and more:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Health check endpoint, returns `200 OK` |
+| `GET /openapi.json` | OpenAPI specification (if `server.build.openAPIDocs` is enabled) |
+| `GET /swagger-ui` | Interactive API documentation (if `server.build.swaggerUI` is enabled) |
+
+This list is not exhaustive. To view all endpoints, run `mastra dev` and visit `http://localhost:4111/swagger-ui`.
 
-### `public` folder
+To add your own endpoints, see [Custom API Routes](https://mastra.ai/docs/v1/server/custom-api-routes).
 
-If a `public` folder exists in `src/mastra`, its contents are copied into the `.build/output` directory during the build process.
+## Troubleshooting
 
-## Running the Server
+### Memory errors during build
 
-Start the HTTP server:
+If you encounter `JavaScript heap out of memory` errors:
 
 ```bash
-node .mastra/output/index.mjs
-```
+NODE_OPTIONS="--max-old-space-size=4096" mastra build
+```
+
+## Related
+
+- [Server Overview](https://mastra.ai/docs/v1/server/mastra-server) - Configure server behavior, middleware, and authentication
+- [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters) - Use Express or Hono instead of `mastra build`
+- [Custom API Routes](https://mastra.ai/docs/v1/server/custom-api-routes) - Add custom HTTP endpoints
+- [Configuration Reference](https://mastra.ai/reference/v1/configuration) - Full configuration options

package/dist/docs/deployment/03-monorepo.md

@@ -2,7 +2,7 @@
 
 # Deploy in a Monorepo
 
-Deploying Mastra in a monorepo follows the same approach as deploying a standalone application. While some [Cloud](https://mastra.ai/guides/v1/deployment) or [Serverless Platform](https://mastra.ai/guides/v1/deployment) providers may introduce extra requirements, the core setup is the same.
+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/v1/deployment/mastra-server).
 
 ## Supported monorepos
 
@@ -18,9 +18,9 @@ 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 monorepo
+## Example structure
 
-In this example, the Mastra application is located at `apps/api`.
+In this example, the Mastra application is located at `apps/api`:
 
 ```
 apps/
@@ -40,31 +40,103 @@ packages/
 package.json
 ```
 
-## Environment variables
+## 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
+```
 
-Environment variables like `OPENAI_API_KEY` should be stored in an `.env` file at the root of the Mastra application `(apps/api)`, for example:
+**yarn:**
 
+```bash
+yarn workspace api build
 ```
-api/
-├── src/
-│   └── mastra/
-├── .env
-├── package.json
-└── tsconfig.json
+
+**turborepo:**
+
+```bash
+turbo run build --filter=api
+```
+
+Your package's `build` script should run `mastra build`:
+
+```json title="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`](https://mastra.ai/reference/v1/configuration#bundlertranspilepackages):
+
+```typescript title="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](https://mastra.ai/docs/v1/mastra-cloud/overview). While the interface may differ between providers, the configuration remains the same.
 
 ![Deployment configuration](/img/monorepo/monorepo-mastra-cloud.jpg)
 
-> **Note:**
-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.
+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/v1/configuration#bundlertranspilepackages) in your Mastra config
+
+## Related
 
-- 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.
+- [Deploy a Mastra Server](https://mastra.ai/docs/v1/deployment/mastra-server) - Core build and deployment guide
+- [Configuration Reference](https://mastra.ai/reference/v1/configuration) - `bundler.transpilePackages` and other options
+- [CLI Reference](https://mastra.ai/reference/v1/cli/mastra) - Build command flags

package/dist/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkSBGBJ7NB_cjs = require('./chunk-SBGBJ7NB.cjs');
-var chunkNWQP6PZQ_cjs = require('./chunk-NWQP6PZQ.cjs');
+var chunkVOI3B5MX_cjs = require('./chunk-VOI3B5MX.cjs');
+var chunkT7NCLSYN_cjs = require('./chunk-T7NCLSYN.cjs');
 var chunkJVBCN3RH_cjs = require('./chunk-JVBCN3RH.cjs');
 
 // src/deploy/base.ts
-var Deployer = class extends chunkSBGBJ7NB_cjs.Bundler {
+var Deployer = class extends chunkVOI3B5MX_cjs.Bundler {
   deps = new chunkJVBCN3RH_cjs.DepsService();
   constructor(args) {
     super(args.name, "DEPLOYER");
@@ -25,7 +25,7 @@ var Deployer = class extends chunkSBGBJ7NB_cjs.Bundler {
 
 // src/build/deployer.ts
 async function getDeployer(entryFile, outputDir, logger) {
-  const result = await chunkNWQP6PZQ_cjs.extractMastraOption("deployer", entryFile, outputDir, logger);
+  const result = await chunkT7NCLSYN_cjs.extractMastraOption("deployer", entryFile, outputDir, logger);
   if (!result) {
     return null;
   }

package/dist/index.js

@@ -1,5 +1,5 @@
-import { Bundler } from './chunk-NGWTN4SJ.js';
-import { extractMastraOption } from './chunk-4NPMVODD.js';
+import { Bundler } from './chunk-SD6NHZ2H.js';
+import { extractMastraOption } from './chunk-HWSYWSD7.js';
 import { DepsService, FileService } from './chunk-DPDWM7HQ.js';
 export { Deps, FileService, createChildProcessLogger, createPinoStream } from './chunk-DPDWM7HQ.js';
 

package/dist/server/index.cjs

@@ -3670,7 +3670,7 @@ var getStudioPath = () => {
     const __filename = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
     __dirname = path.dirname(__filename);
   }
-  const studioPath = process.env.MASTRA_STUDIO_PATH || path.join(__dirname, "playground");
+  const studioPath = process.env.MASTRA_STUDIO_PATH || path.join(__dirname, "studio");
   return studioPath;
 };
 function getToolExports(tools$1) {
@@ -3821,7 +3821,7 @@ async function createHonoServer(mastra, options = {
   }
   const serverOptions = mastra.getServer();
   const studioBasePath = chunk5TYVF4KJ_cjs.normalizeStudioBase(serverOptions?.studioBase ?? "/");
-  if (options?.playground) {
+  if (options?.studio) {
     app.get(
       `${studioBasePath}/refresh-events`,
       describeRoute({
@@ -3874,8 +3874,8 @@ async function createHonoServer(mastra, options = {
     if (requestPath.includes(".") && !requestPath.endsWith(".html")) {
       return await next();
     }
-    const isPlaygroundRoute = studioBasePath === "" || requestPath === studioBasePath || requestPath.startsWith(`${studioBasePath}/`);
-    if (options?.playground && isPlaygroundRoute) {
+    const isStudioRoute = studioBasePath === "" || requestPath === studioBasePath || requestPath.startsWith(`${studioBasePath}/`);
+    if (options?.studio && isStudioRoute) {
       const studioPath = getStudioPath();
       let indexHtml = await promises.readFile(path.join(studioPath, "index.html"), "utf-8");
       const port = serverOptions?.port ?? (Number(process.env.PORT) || 4111);
@@ -3884,22 +3884,24 @@ async function createHonoServer(mastra, options = {
       const key = serverOptions?.https?.key ?? (process.env.MASTRA_HTTPS_KEY ? Buffer.from(process.env.MASTRA_HTTPS_KEY, "base64") : void 0);
       const cert = serverOptions?.https?.cert ?? (process.env.MASTRA_HTTPS_CERT ? Buffer.from(process.env.MASTRA_HTTPS_CERT, "base64") : void 0);
       const protocol = key && cert ? "https" : "http";
+      const cloudApiEndpoint = process.env.MASTRA_CLOUD_API_ENDPOINT || "";
       indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_HOST%%'`, `'${host}'`);
       indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_PORT%%'`, `'${port}'`);
       indexHtml = indexHtml.replace(`'%%MASTRA_HIDE_CLOUD_CTA%%'`, `'${hideCloudCta}'`);
       indexHtml = indexHtml.replace(`'%%MASTRA_SERVER_PROTOCOL%%'`, `'${protocol}'`);
+      indexHtml = indexHtml.replace(`'%%MASTRA_CLOUD_API_ENDPOINT%%'`, `'${cloudApiEndpoint}'`);
       indexHtml = indexHtml.replaceAll("%%MASTRA_STUDIO_BASE_PATH%%", studioBasePath);
       return c.newResponse(indexHtml, 200, { "Content-Type": "text/html" });
     }
     return c.newResponse(html2, 200, { "Content-Type": "text/html" });
   });
-  if (options?.playground) {
-    const studioPath = getStudioPath();
-    const playgroundPath = studioBasePath ? `${studioBasePath}/*` : "*";
+  if (options?.studio) {
+    const studioRootPath = getStudioPath();
+    const studioPath = studioBasePath ? `${studioBasePath}/*` : "*";
     app.use(
-      playgroundPath,
+      studioPath,
       serveStatic({
-        root: studioPath,
+        root: studioRootPath,
         rewriteRequestPath: (path) => {
           if (studioBasePath && path.startsWith(studioBasePath)) {
             return path.slice(studioBasePath.length);
@@ -3936,7 +3938,7 @@ async function createNodeServer(mastra, options = { tools: {} }) {
     () => {
       const logger2 = mastra.getLogger();
       logger2.info(` Mastra API running on ${protocol}://${host}:${port}/api`);
-      if (options?.playground) {
+      if (options?.studio) {
         const studioBasePath = chunk5TYVF4KJ_cjs.normalizeStudioBase(serverOptions?.studioBase ?? "/");
         const studioUrl = `${protocol}://${host}:${port}${studioBasePath}`;
         logger2.info(`\u{1F468}\u200D\u{1F4BB} Studio available at ${studioUrl}`);