@opble/mastra-kit

Common middleware and utilities for Mastra servers.

Installation

npm install @opble/mastra-kit

Middleware

CORS — createCorsMiddleware

Wraps Hono's built-in CORS middleware with wildcard-origin matching and environment-variable-driven configuration.

Environment variables

| Variable | Default | Description | |---|---|---| | CORS_ALLOWED_ORIGINS | * | Comma-separated list of allowed origins | | CORS_ALLOWED_HEADERS | (empty — browser default) | Comma-separated list of allowed request headers | | CORS_ALLOWED_METHODS | GET,HEAD,PUT,POST,DELETE,PATCH | Comma-separated list of allowed HTTP methods |

CORS_ALLOWED_ORIGINS supports:

• Exact origins: https://example.com
• Global wildcard: *
• Subdomain wildcards: https://*.example.com

Basic usage (env-driven)

Set the environment variables, then register the middleware on your Mastra server:

CORS_ALLOWED_ORIGINS=https://app.example.com,https://*.staging.example.com

import { Mastra } from 'mastra';
import { createCorsMiddleware } from '@opble/mastra-kit';

export const mastra = new Mastra({
  server: {
    middleware: [
      { path: '/*', handler: createCorsMiddleware() as any },
    ],
  },
});

Note: The as any cast is required because @mastra/core vendors its own copy of Hono's types internally, causing a structural type mismatch at the assignment site. The middleware itself is fully type-safe — only the assignment into Mastra's config needs the cast.

Options (override env vars)

createCorsMiddleware({
  allowOrigins: ['https://app.example.com', 'https://*.staging.example.com'],
  allowHeaders: ['Content-Type', 'Authorization'],
  allowMethods: ['GET', 'POST'],
})

Options reference

| Option | Type | Default | Description | |---|---|---|---| | allowOrigins | string \| string[] | CORS_ALLOWED_ORIGINS env | Allowed origins — exact strings or wildcard patterns | | allowHeaders | string[] | CORS_ALLOWED_HEADERS env | Allowed request headers | | allowMethods | string[] | CORS_ALLOWED_METHODS env | Allowed HTTP methods |

Health check — createHealthHandler

Returns { status: 'ok' }. Register it on whichever path you want via Mastra's server apiRoutes config.

Basic usage

import { Mastra } from 'mastra';
import { registerApiRoute } from '@mastra/core/server';
import { createHealthHandler } from '@opble/mastra-kit';

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/health', {
        method: 'GET',
        handler: createHealthHandler() as any,
      }),
    ],
  },
});

Note: The as any cast is required because @mastra/core vendors its own copy of Hono's types internally, causing a structural type mismatch at the assignment site. The handler itself is fully type-safe — only the assignment into Mastra's config needs the cast.

Options

createHealthHandler({
  extra: { version: '1.2.3' },  // extra fields merged into the response body
})

Options reference

| Option | Type | Default | Description | |---|---|---|---| | extra | Record<string, unknown> | — | Additional fields merged into the JSON response body |

License

MIT