Adaptateur Express

Le package @mastra/express fournit un adaptateur de serveur permettant d'exécuter Mastra avec Express. Pour les concepts généraux relatifs aux adaptateurs (options du constructeur, processus d'initialisation, etc.), consultez Adaptateurs de serveur.

Installation

Installez l'adaptateur Express et le framework Express :

npm

npm install @mastra/express@latest express

pnpm

pnpm add @mastra/express@latest express

Yarn

yarn add @mastra/express@latest express

Bun

bun add @mastra/express@latest express

Exemple d'utilisation

server.ts

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)

openapiPath?:

string

= ''

Chemin servant la spécification OpenAPI (par exemple, /openapi.json)

bodyLimitOptions?:

{ maxSize: number, onError: (err) => unknown }

Limites de taille du corps des requêtes

streamOptions?:

{ redact?: boolean }

= { redact: true }

Configuration du masquage des flux. Lorsque cette option vaut true, les données sensibles sont masquées dans les flux.

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 :

server.ts

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(). Pour les routes Express brutes montées directement sur app, utilisez createAuthMiddleware() :

server.ts

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 :

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() :

server.ts

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 pour plus de détails.

Exemples

• Adaptateur Express : configuration de base d'un serveur Express

Voir aussi

• Adaptateurs de serveur : concepts communs aux adaptateurs
• Référence de MastraServer : référence complète de l'API
• Référence de createRoute() : création de routes personnalisées avec typage sûr