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

# Adaptateur Express

Le package `@mastra/express` fournit un adaptateur de serveur permettant d'exécuter Mastra avec [Express](https://expressjs.com). Pour les concepts généraux relatifs aux adaptateurs (options du constructeur, processus d'initialisation, etc.), consultez [Adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters).

## Installation

Installez l'adaptateur Express et le framework Express :

**npm**:

```bash
npm install @mastra/express@latest express
```

**pnpm**:

```bash
pnpm add @mastra/express@latest express
```

**Yarn**:

```bash
yarn add @mastra/express@latest express
```

**Bun**:

```bash
bun add @mastra/express@latest express
```

## Exemple d'utilisation

```typescript
import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
app.use(express.json()) // Required for body parsing

const server = new MastraServer({ app, mastra })
await server.init()

app.listen(4111, () => {
  console.log('Server running on port 4111')
})
```

> **Remarque:** Express nécessite le middleware `express.json()` pour analyser les corps JSON. Ajoutez-le avant de créer le `MastraServer`.

## Paramètres du constructeur

**app** (`Application`): Instance de l'application Express

**mastra** (`Mastra`): Instance de Mastra

**prefix** (`string`): Préfixe du chemin des routes (par exemple, /api/v2) (Default: `''`)

**openapiPath** (`string`): Chemin servant la spécification OpenAPI (par exemple, /openapi.json) (Default: `''`)

**bodyLimitOptions** (`{ maxSize: number, onError: (err) => unknown }`): Limites de taille du corps des requêtes

**streamOptions** (`{ redact?: boolean }`): Configuration du masquage des flux. Lorsque cette option vaut true, les données sensibles sont masquées dans les flux. (Default: `{ redact: true }`)

**customRouteAuthConfig** (`Map<string, boolean>`): Remplacements de l'authentification par route. Les clés suivent la forme METHOD:PATH (par exemple, GET:/api/health). La valeur false rend la route publique, tandis que true exige une authentification.

**tools** (`Record<string, Tool>`): Tools disponibles pour le serveur

**taskStore** (`InMemoryTaskStore`): Stockage de tâches pour les opérations A2A (Agent-to-Agent)

**mcpOptions** (`MCPOptions`): Options de transport MCP. Définissez serverless: true pour les environnements sans état tels que Cloudflare Workers ou Vercel Edge.

## Différences par rapport à Hono

| Aspect                  | Express                            | Hono                           |
| ----------------------- | ---------------------------------- | ------------------------------ |
| Analyse du corps        | Nécessite `express.json()`         | Gérée par le framework         |
| Stockage du contexte    | `res.locals`                       | `c.get()` / `c.set()`          |
| Signature du middleware | `(req, res, next)`                 | `(c, next)`                    |
| Streaming               | `res.write()` / `res.end()`        | Fonction utilitaire `stream()` |
| AbortSignal             | Créé à partir de `req.on('close')` | `c.req.raw.signal`             |

## Ajout de routes personnalisées

Ajoutez les routes directement à l'application Express :

```typescript
const app = express()
app.use(express.json())

const server = new MastraServer({ app, mastra })

// Before init - runs before Mastra middleware
app.get('/early-health', (req, res) => res.json({ status: 'ok' }))

await server.init()

// After init - has access to Mastra context
app.get('/custom', (req, res) => {
  const mastraInstance = res.locals.mastra
  res.json({ agents: Object.keys(mastraInstance.listAgents()) })
})

app.listen(4111)
```

> **Astuce:** Les routes ajoutées avant `init()` s'exécutent sans contexte Mastra. Ajoutez-les après `init()` pour accéder à l'instance Mastra et au contexte de la requête.

Pour bénéficier de l'authentification gérée par Mastra et de métadonnées de route telles que `requiresAuth`, privilégiez [`registerApiRoute()`](https://mastra.zisheng.pro/fr/reference/server/register-api-route). Pour les routes Express brutes montées directement sur `app`, utilisez `createAuthMiddleware()` :

```typescript
import express from 'express'
import { createAuthMiddleware, MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
app.use(express.json())

const server = new MastraServer({ app, mastra })
await server.init()

app.get('/custom/protected', createAuthMiddleware({ mastra }), (req, res) => {
  const user = res.locals.requestContext.get('user')
  res.json({ user })
})

app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), (req, res) => {
  res.json({ ok: true })
})
```

## Accès au contexte

Dans les middlewares et les routes Express, accédez au contexte Mastra au moyen de `res.locals` :

```typescript
app.get('/custom', (req, res) => {
  const mastra = res.locals.mastra
  const requestContext = res.locals.requestContext
  const abortSignal = res.locals.abortSignal

  const agent = mastra.getAgent('myAgent')
  res.json({ agent: agent.name })
})
```

Propriétés disponibles dans `res.locals` :

| Clé                     | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `mastra`                | Instance de Mastra                                             |
| `requestContext`        | Map du contexte de la requête                                  |
| `abortSignal`           | Signal d'annulation de la requête                              |
| `tools`                 | Tools disponibles                                              |
| `taskStore`             | Stockage de tâches pour les opérations A2A                     |
| `customRouteAuthConfig` | Remplacements de l'authentification par route                  |
| `user`                  | Utilisateur authentifié (si l'authentification est configurée) |

## Ajout de middleware

Ajoutez un middleware Express avant ou après `init()` :

```typescript
const app = express()
app.use(express.json())

// Middleware before init
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`)
  next()
})

const server = new MastraServer({ app, mastra })
await server.init()

// Middleware after init has access to Mastra context
app.use((req, res, next) => {
  const mastra = res.locals.mastra
  next()
})
```

## Initialisation manuelle

Pour personnaliser l'ordre des middlewares, appelez chaque méthode séparément au lieu d'utiliser `init()`. Consultez [l'initialisation manuelle](https://mastra.zisheng.pro/fr/docs/server/server-adapters) pour plus de détails.

## Exemples

- [Adaptateur Express](https://github.com/mastra-ai/mastra/tree/main/examples/server-express-adapter) : configuration de base d'un serveur Express

## Voir aussi

- [Adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) : concepts communs aux adaptateurs
- [Référence de MastraServer](https://mastra.zisheng.pro/fr/reference/server/mastra-server) : référence complète de l'API
- [Référence de createRoute()](https://mastra.zisheng.pro/fr/reference/server/create-route) : création de routes personnalisées avec typage sûr