Deployer

The Deployer handles the deployment of standalone Mastra applications by packaging code and managing environment files while serving applications through the Hono framework. Concrete implementations must define the deploy method for specific deployment targets.

Usage example

If you want to create a custom deployer, you can extend the abstract Deployer class and implement the deploy method with your specific deployment logic. Here's an example:

import { Deployer } from '@mastra/deployer'

class CustomDeployer extends Deployer {
  constructor() {
    super({ name: 'custom-deployer' })
  }

  async deploy(outputDirectory: string): Promise<void> {
    // Prepare the output directory
    await this.prepare(outputDirectory)

    // Bundle the application
    await this._bundle('server.ts', 'mastra.ts', outputDirectory)

    // Custom deployment logic
  }
}

Parameters

Constructor parameters

args:

object

Configuration options for the Deployer.

args.name:

string

A unique name for the deployer instance.

deploy Parameters

outputDirectory:

string

The directory where the bundled and deployment-ready application will be output.

Methods

getEnvFiles:

() => Promise<string[]>

Returns the environment files to be used during deployment. By default, it returns every existing file among '.env', '.env.local', and '.env.production', in that order (lowest to highest precedence).

deploy:

(outputDirectory: string) => Promise<void>

Abstract method that must be implemented by subclasses. Handles the deployment process to the specified output directory.

Inherited methods from bundler

The Deployer class inherits the following key methods from the Bundler class:

prepare:

(outputDirectory: string) => Promise<void>

Prepares the output directory by cleaning it and creating necessary subdirectories.

writePackageJson:

(outputDirectory: string, dependencies: Map<string, string>) => Promise<void>

Generates a package.json file in the output directory with the specified dependencies.

_bundle:

(serverFile: string, mastraEntryFile: string, outputDirectory: string, bundleLocation?: string) => Promise<void>

Bundles the application using the specified server and Mastra entry files.

Core concepts

Deployment Lifecycle

The Deployer abstract class implements a structured deployment lifecycle:

1. Initialization: The deployer is initialized with a name and creates a Deps instance for dependency management.
2. Environment Setup: The getEnvFiles method identifies the environment files (.env, .env.local, .env.production) to be used during deployment.
3. Preparation: The prepare method (inherited from Bundler) cleans the output directory and creates necessary subdirectories.
4. Bundling: The _bundle method (inherited from Bundler) packages the application code and its dependencies.
5. Deployment: The abstract deploy method is implemented by subclasses to handle the actual deployment process.

Environment File Management

The Deployer class includes built-in support for environment file management through the getEnvFiles method. This method:

• Looks for environment files in a predefined order, from lowest to highest precedence: .env, .env.local, .env.production
• Returns every file that exists, in that order, so values in later files override earlier ones
• Returns an empty array if no environment files are found

getEnvFiles(): Promise<string[]> {
  const possibleFiles = ['.env', '.env.local', '.env.production'];
  const fileService = new FileService();

  return Promise.resolve(fileService.getExistingFiles(possibleFiles));
}

Bundling and Deployment Relationship

The Deployer class extends the Bundler class, establishing a clear relationship between bundling and deployment:

1. Bundling as a Prerequisite: Bundling is a prerequisite step for deployment, where the application code is packaged into a deployable format.
2. Shared Infrastructure: Both bundling and deployment share common infrastructure like dependency management and file system operations.
3. Specialized Deployment Logic: While bundling focuses on code packaging, deployment adds environment-specific logic for deploying the bundled code.
4. Extensibility: The abstract deploy method allows for creating specialized deployers for different target environments.