Hono Server Adapter

Hono is an ultrafast web framework for the edge that works on any JavaScript runtime. The Hono adapter lets you deploy Mastra on Cloudflare Workers, Deno, Bun, and Node.js.

Installation

npm install @mastra/hono hono

Basic Setup

Import dependencies

import { Hono } from 'hono';
import { Mastra } from '@mastra/core';
import { MastraServer } from '@mastra/hono';

Create Mastra instance

const mastra = new Mastra({
  // Your Mastra configuration
});

Create Hono app and mount Mastra

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

export default app;

Complete Example

import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { Mastra } from '@mastra/core';
import { MastraServer } from '@mastra/hono';
import { Agent } from '@mastra/core/agent';
import { createOpenAI } from '@ai-sdk/openai';

// Create an agent
const agent = new Agent({
  name: 'assistant',
  instructions: 'You are a helpful assistant.',
  model: createOpenAI({
    apiKey: process.env.OPENAI_API_KEY!,
  }).chat('gpt-4o'),
});

// Create Mastra instance
const mastra = new Mastra({
  agents: { assistant: agent },
});

// Create Hono app
const app = new Hono();

// Add middleware
app.use('*', cors());

// Custom routes
app.get('/', (c) => {
  return c.json({ message: 'Mastra API' });
});

// Mount Mastra server
const server = new MastraServer({ 
  mastra, 
  app,
  prefix: '/api/mastra',
});

// Start server
const port = 4111;
serve({
  fetch: app.fetch,
  port,
});

console.log(`Server running on http://localhost:${port}`);

Configuration Options

mastra

Mastra

required

Mastra instance to serve

app

Hono

required

Hono application instance

prefix

string

default:"/api/mastra"

URL prefix for Mastra routes

bodyLimitOptions

object

Body size limits for uploads:

{
  maxSize: 10 * 1024 * 1024, // 10MB
  onError: (error) => ({ error: 'File too large' })
}

streamOptions

object

Streaming configuration:

{
  redact: true // Redact sensitive data in streams
}

Deployment Targets

Node.js

import { serve } from '@hono/node-server';
import { Hono } from 'hono';

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

serve({
  fetch: app.fetch,
  port: 4111,
});

Cloudflare Workers

import { Hono } from 'hono';
import { MastraServer } from '@mastra/hono';

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

export default app;

wrangler.toml

name = "mastra-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[build]
command = "npm run build"

Bun

import { Hono } from 'hono';

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

export default {
  fetch: app.fetch,
  port: 4111,
};

Deno

import { Hono } from 'https://deno.land/x/hono/mod.ts';
import { serve } from 'https://deno.land/std/http/server.ts';

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

serve(app.fetch);

Middleware

CORS

import { cors } from 'hono/cors';

app.use('*', cors({
  origin: 'http://localhost:3000',
  credentials: true,
}));

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

Authentication

import { MastraAuthClerk } from '@mastra/auth-clerk';

const mastra = new Mastra({
  server: {
    auth: new MastraAuthClerk(),
  },
});

const app = new Hono();
const server = new MastraServer({ mastra, app });
// Auth middleware is automatically added

Logging

import { logger } from 'hono/logger';

app.use('*', logger());
const server = new MastraServer({ mastra, app });

Rate Limiting

import { rateLimiter } from 'hono-rate-limiter';

app.use(
  '*',
  rateLimiter({
    windowMs: 15 * 60 * 1000, // 15 minutes
    limit: 100, // max 100 requests per window
  })
);

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

Custom Routes

Add Custom Endpoints

const app = new Hono();

// Custom routes before Mastra
app.get('/health', (c) => {
  return c.json({ status: 'ok' });
});

app.post('/custom/endpoint', async (c) => {
  const body = await c.req.json();
  return c.json({ received: body });
});

// Mount Mastra
const server = new MastraServer({ mastra, app });

Access Mastra Context

app.get('/custom/agent-status', async (c) => {
  const mastra = c.get('mastra'); // Access Mastra instance
  const agents = Object.keys(mastra.agents || {});
  
  return c.json({ agents });
});

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

Streaming

Hono adapter supports SSE streaming for agent responses:

// Mastra automatically handles streaming
const response = await fetch('http://localhost:4111/api/mastra/agents/assistant/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});

const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

File Uploads

Handle file uploads with body limits:

const server = new MastraServer({ 
  mastra, 
  app,
  bodyLimitOptions: {
    maxSize: 50 * 1024 * 1024, // 50MB
    onError: (error) => ({
      error: 'File size exceeds 50MB limit',
      code: 'FILE_TOO_LARGE',
    }),
  },
});

Error Handling

app.onError((err, c) => {
  console.error('Error:', err);
  
  return c.json(
    { 
      error: err.message,
      stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
    },
    500
  );
});

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

Testing

import { Hono } from 'hono';
import { MastraServer } from '@mastra/hono';

describe('Mastra API', () => {
  const app = new Hono();
  const server = new MastraServer({ mastra, app });

  it('should return agents list', async () => {
    const res = await app.request('/api/mastra/agents');
    expect(res.status).toBe(200);
    
    const data = await res.json();
    expect(data).toHaveProperty('agents');
  });
});

Best Practices

Edge-First

Hono is optimized for edge runtimes. Use Cloudflare Workers for global low-latency deployment.

Middleware Order

Add middleware before mounting MastraServer:

app.use('*', cors());
app.use('*', logger());
const server = new MastraServer({ mastra, app });

Type Safety

Leverage Hono’s TypeScript types:

type Variables = {
  mastra: Mastra;
};
const app = new Hono<{ Variables: Variables }>();

Body Limits

Configure appropriate body limits for your use case (file uploads, large JSON payloads).

Performance

Benchmarks

Hono is one of the fastest web frameworks:

~4x faster than Express
Minimal overhead
Optimized for edge runtimes

Optimizations

// Enable streaming for large responses
streamOptions: {
  redact: true, // Redact sensitive data
}

// Set appropriate body limits
bodyLimitOptions: {
  maxSize: 10 * 1024 * 1024, // 10MB
}

Express Adapter

Traditional Node.js framework adapter

Authentication

Add authentication to your Mastra API

Hono Documentation

Official Hono documentation

Cloudflare Workers

Deploy Hono apps to the edge

Overview

Storage

Vector Stores

Auth Providers

Server Adapters

Hono Server Adapter

Installation

Basic Setup

Complete Example

Configuration Options

Deployment Targets

Node.js

Cloudflare Workers

Bun

Deno

Middleware

CORS

Authentication

Logging

Rate Limiting

Custom Routes

Add Custom Endpoints

Access Mastra Context

Streaming

File Uploads

Error Handling

Testing

Best Practices

Edge-First

Middleware Order

Type Safety

Body Limits

Performance

Benchmarks

Optimizations

Express Adapter

Authentication

Hono Documentation

Cloudflare Workers

Build docs developers (and LLMs) love

Overview

Storage

Vector Stores

Auth Providers

Server Adapters

​Installation

​Basic Setup

​Complete Example

​Configuration Options

​Deployment Targets

​Node.js

​Cloudflare Workers

​Bun

​Deno

​Middleware

​CORS

​Authentication

​Logging

​Rate Limiting

​Custom Routes

​Add Custom Endpoints

​Access Mastra Context

​Streaming

​File Uploads

​Error Handling

​Testing

​Best Practices

Edge-First

Middleware Order

Type Safety

Body Limits

​Performance

​Benchmarks

​Optimizations

​Related Resources

Express Adapter

Authentication

Hono Documentation

Cloudflare Workers

Build docs developers (and LLMs) love

Installation

Basic Setup

Complete Example

Configuration Options

Deployment Targets

Node.js

Cloudflare Workers

Bun

Deno

Middleware

CORS

Authentication

Logging

Rate Limiting

Custom Routes

Add Custom Endpoints

Access Mastra Context

Streaming

File Uploads

Error Handling

Testing

Best Practices

Performance

Benchmarks

Optimizations

Related Resources