> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server).

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

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

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

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

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

```typescript
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](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server) 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`](https://mastra.zisheng.pro/fr/reference/configuration) dans votre configuration Mastra

## Pages connexes

- [Déployer un serveur Mastra](https://mastra.zisheng.pro/fr/docs/deployment/mastra-server) : guide principal de build et de déploiement
- [Référence de configuration](https://mastra.zisheng.pro/fr/reference/configuration) : `bundler.transpilePackages` et autres options
- [Référence de la CLI](https://mastra.zisheng.pro/fr/reference/cli/mastra) : indicateurs de la commande de build