CloudflareDeployer

CloudflareDeployer は Mastra サーバーをバンドルし、Cloudflare の wrangler 設定に準拠した wrangler.jsonc ファイルを生成します。Cloudflare はこれを Cloudflare Worker としてデプロイします。

インストール

CloudflareDeployer を使用するには、@mastra/deployer-cloudflare パッケージをインストールします。

npm

npm install @mastra/deployer-cloudflare@latest

pnpm

pnpm add @mastra/deployer-cloudflare@latest

Yarn

yarn add @mastra/deployer-cloudflare@latest

Bun

bun add @mastra/deployer-cloudflare@latest

使用例

CloudflareDeployer をインポートし、Mastra 設定で deployer に指定します。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  deployer: new CloudflareDeployer({
    name: 'your-project-name',
    routes: [
      {
        pattern: 'example.com/*',
        zone_name: 'example.com',
        custom_domain: true,
      },
    ],
    vars: {
      NODE_ENV: 'production',
    },
    d1_databases: [
      {
        binding: 'DB',
        database_name: 'my-database',
        database_id: 'd1-database-id',
        preview_database_id: 'your-preview-database-id',
      },
    ],
    kv_namespaces: [
      {
        binding: 'CACHE',
        id: 'kv-namespace-id',
      },
    ],
  }),
})

コンストラクターオプション

CloudflareDeployer コンストラクターは、wrangler.jsonc と同じ設定オプションを受け取ります。利用可能なすべてのオプションについては、Wrangler 設定のドキュメントを参照してください。

シークレット

.env ファイルの環境変数は wrangler.jsonc に書き込まれません。これにより、シークレットがソース管理にコミットされるのを防ぎます。

.env のシークレットを Cloudflare Worker で利用できるようにするには、Cloudflare Secrets としてアップロードします。

npx wrangler secret bulk .env

CloudflareDeployer コンストラクターの vars は、NODE_ENV のような機密性のない設定値にのみ使用してください。

ビルド出力

mastra build を実行すると、deployer は Cloudflare の wrangler 設定に準拠した wrangler.jsonc ファイルを生成します。このファイルは .mastra/output 内のファイルを参照するため、Wrangler でデプロイする前に mastra build を実行する必要があります。

Cloudflare バインディング

Cloudflare deployer を使用すると、Mastra 設定ファイルで cloudflare:workers からランタイムバインディングをインポートできます。Mastra は mastra build 中に cloudflare:workers のようなプロトコルベースのランタイムインポートを自動的に保持し、npm 依存関係としてインストールしようとはしません。

src/mastra/index.ts

import { env } from 'cloudflare:workers'
import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'
import { CloudflareDeployer } from '@mastra/deployer-cloudflare'

export const mastra = new Mastra({
  deployer: new CloudflareDeployer({
    name: 'my-worker',
    kv_namespaces: [{ binding: 'CACHE', id: 'your-kv-namespace-id' }],
  }),
  server: {
    apiRoutes: [
      registerApiRoute('/bindings', {
        method: 'GET',
        requiresAuth: false,
        handler: async c => {
          await env.CACHE.put('status', 'ok')
          return c.json({ status: await env.CACHE.get('status') })
        },
      }),
    ],
  },
})

バインディングは new Mastra({...}) 内に直接記述する

Mastra の Babel プラグインは、実行時に env を利用できるよう new Mastra(...) の評価を遅延させます。この呼び出しの外にあるコードは、env に値が設定される前のモジュール読み込み時に評価されます。

// ✅ Works — binding is inside new Mastra(), so it's deferred
export const mastra = new Mastra({
  storage: new D1Store({ binding: env.DB }),
})

// ❌ Breaks — env.DB is undefined at module load
const storage = new D1Store({ binding: env.DB })
export const mastra = new Mastra({ storage })