Déployer un serveur Mastra

Mastra compile votre application en un serveur Node.js autonome pouvant s'exécuter sur toute plateforme prenant en charge Node.js, Bun ou Deno.

astuce

Ce guide traite du déploiement du serveur autonome généré par mastra build. Si vous devez intégrer Mastra à une application Express ou Hono existante, consultez plutôt les adaptateurs de serveur.

Compiler votre application

Exécutez la commande de build depuis la racine de votre projet :

mastra build

Cette commande crée un répertoire .mastra contenant votre serveur prêt pour la production. Consultez la référence de mastra build pour connaître toutes les options disponibles.

Résultat du build

Après le build, Mastra crée la structure suivante :

.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)

Le répertoire output est autonome. Vous pouvez le copier sur n'importe quel serveur et l'exécuter directement.

Exécuter le serveur

Démarrez le serveur avec la CLI Mastra :

mastra start

Vous pouvez également l'exécuter directement avec Node.js :

node .mastra/output/index.mjs

La commande mastra start fournit des fonctionnalités supplémentaires :

• chargement des variables d'environnement depuis .env.production et .env ;
• messages d'erreur utiles en cas de modules manquants ;
• gestion des signaux du processus pour un arrêt propre.

Consultez la référence de mastra start pour connaître toutes les options disponibles.

Configuration du build

Configuration au moment du build

Mastra lit les options bundler, deployer et server pendant le build de votre application. Conservez ces options comme propriétés directes de l'objet transmis à new Mastra() afin que le build puisse les extraire.

La structure de fichier d'entrée suivante fonctionne :

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})

La valeur de chaque option peut provenir d'une variable, d'un import ou d'un appel de fonction. L'option elle-même doit rester une propriété directe. Ne masquez pas les options de build derrière un appel de fabrique ou une décomposition d'objet :

src/mastra/index.ts

const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })

Lorsque Mastra ne peut pas extraire une option, il applique le comportement de build par défaut pour celle-ci. Consultez la référence de configuration pour les paramètres bundler, deployer et server disponibles.

Dossier public

Si un dossier public existe dans votre répertoire Mastra (src/mastra/public), son contenu est copié dans le répertoire de sortie pendant le build. Le serveur distribue ces fichiers comme ressources statiques.

Configuration de Mastra

Le processus de build respecte la configuration de votre instance Mastra. Pour le comportement du serveur, notamment CORS, les délais d'expiration et les middlewares, consultez la présentation du serveur. Pour toutes les options disponibles, consultez la référence de configuration.

Processus de build

Le build suit les étapes suivantes :

1. Localisation du fichier d'entrée : recherche index.ts ou index.js dans votre répertoire Mastra.
2. Découverte des outils : recherche les fichiers d'outils correspondant à {mastraDir}/tools/**/*.{js,ts}, en excluant les fichiers de test.
3. Analyse des dépendances : détermine quels packages regrouper et lesquels installer séparément.
4. Regroupement du code : utilise Rollup avec élimination du code mort et, facultativement, des source maps.
5. Génération du serveur : crée un serveur HTTP basé sur Hono sous la forme index.mjs.
6. Installation des dépendances : exécute npm install dans le répertoire de sortie.
7. Copie des ressources : copie le dossier public et le fichier .npmrc s'ils existent.

Variables d'environnement

Variable	Description
PORT	Port du serveur (par défaut : 4111)
MASTRA_STUDIO_PATH	Chemin du répertoire de build de Studio (par défaut : ./playground)
MASTRA_SKIP_DOTENV	Ignore le chargement des fichiers .env lorsqu'elle est définie
NODE_OPTIONS	Options Node.js (par exemple --max-old-space-size=4096 en cas de problèmes de mémoire pendant le build)

Points de terminaison du serveur

Le serveur compilé expose des points de terminaison pour les contrôles de santé, les Agents, les Workflows et bien plus :

Point de terminaison	Description
GET /health	Point de terminaison de contrôle de santé, renvoie 200 OK
GET /api/openapi.json	Spécification OpenAPI (si server.build.openAPIDocs est activé).
GET /swagger-ui	Documentation interactive de l'API (si server.build.swaggerUI est activé)

Cette liste n'est pas exhaustive. Pour afficher tous les points de terminaison, exécutez mastra dev puis ouvrez http://localhost:4111/swagger-ui.

Pour ajouter vos propres points de terminaison, consultez les routes d'API personnalisées.

Dépannage

Erreurs de mémoire pendant le build

Si vous rencontrez des erreurs JavaScript heap out of memory :

NODE_OPTIONS="--max-old-space-size=4096" mastra build

Voir aussi

• Présentation du serveur : configurer le comportement du serveur, les middlewares et l'authentification
• Adaptateurs de serveur : utiliser Express ou Hono à la place de mastra build
• Routes d'API personnalisées : ajouter des points de terminaison HTTP personnalisés
• Référence de configuration : toutes les options de configuration