Déployer dans un monorepo

Le déploiement de Mastra dans un monorepo suit le même processus que celui d’une application autonome. Ce guide présente les considérations propres aux monorepos. Pour les principales étapes de build et de déploiement, consultez Déployer un serveur Mastra.

Monorepos pris en charge

Mastra fonctionne avec :

• npm workspaces
• pnpm workspaces
• Yarn workspaces
• Turborepo

Limitations connues :

• Workspaces Bun — prise en charge partielle ; problèmes connus
• Nx — vous pouvez utiliser les stratégies de dépendances prises en charge par Nx, mais vos packages de Workspace doivent contenir des fichiers package.json

Exemple de structure

Dans cet exemple, l’application Mastra se trouve dans apps/api :

apps/
├── api/
│   ├── src/
│   │   └── mastra/
│   │       ├── agents/
│   │       ├── tools/
│   │       ├── workflows/
│   │       └── index.ts
│   ├── package.json
│   └── tsconfig.json
└── web/
packages/
├── ui/
└── utils/
package.json

Créer un build depuis un monorepo

Utilisez l’outil de votre monorepo pour exécuter la commande de build depuis le bon package. Aucun indicateur spécial n’est nécessaire.

Exemples :

npm

npm run build --workspace=apps/api

pnpm

pnpm --filter api run build

yarn

yarn workspace api build

Turborepo

turbo run build --filter=api

Le script build de votre package doit exécuter mastra build :

apps/api/package.json

{
  "scripts": {
    "build": "mastra build"
  }
}

Packages du Workspace

Lorsque votre application Mastra importe d’autres packages du Workspace, Mastra les gère automatiquement :

• Si le package est précompilé (par exemple avec tsc ou tsdown), Mastra importe le JavaScript compilé
• Si le package contient du TypeScript non compilé, Mastra le transpile pendant le build

Dans la plupart des configurations, cela fonctionne sans réglage supplémentaire. Si vous rencontrez des problèmes d’import de packages du Workspace, ajoutez le package à transpilePackages :

src/mastra/index.ts

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/utils'],
  },
})

Conservez bundler comme propriété directe de l’objet transmis à new Mastra(). Consultez la configuration au moment du build pour connaître la structure de fichier d’entrée prise en charge.

Variables d’environnement

Stockez les fichiers .env dans le répertoire de l’application Mastra (par exemple, apps/api/.env), et non à la racine du monorepo.

Configuration du déploiement

Lors d’un déploiement chez un Provider cloud, vérifiez que le package approprié est sélectionné comme cible. Choisir la racine du monorepo plutôt que le répertoire de l’application (par exemple, apps/api) est une erreur courante.

La plupart des Providers permettent d’indiquer le répertoire racine dans leur tableau de bord ou leur fichier de configuration.

Gestion des dépendances

Conservez des dépendances cohérentes afin d’éviter les conflits de versions et les erreurs de build :

• Utilisez un fichier de verrouillage unique à la racine du monorepo afin que tous les packages résolvent les mêmes versions
• Alignez les versions des bibliothèques partagées (telles que Mastra ou les frameworks) afin d’éviter les doublons

Résolution des problèmes

Package du Workspace introuvable

Si Mastra ne parvient pas à résoudre un package du Workspace, vérifiez que :

• Le package figure dans les dépendances de votre package.json
• Votre fichier de verrouillage est à jour (pnpm install, npm install, etc.)
• Le package possède un champ main ou exports valide dans son package.json

Erreurs TypeScript provenant des packages du Workspace

Si des packages du Workspace non compilés provoquent des erreurs de types :

• Créez d’abord le build du package (recommandé pour accélérer les builds Mastra)
• Ajoutez le package à transpilePackages dans votre configuration Mastra

Pages connexes

• Déployer un serveur Mastra : guide principal de build et de déploiement
• Référence de configuration : bundler.transpilePackages et autres options
• Référence de la CLI : indicateurs de la commande de build