Vite/React プロジェクトに Mastra を統合する

Mastra は Vite と統合されており、次のことを容易にします:

柔軟な API を構築して、AI 搭載の機能を提供できる
フロントエンドとバックエンドを単一のコードベースにまとめ、デプロイを簡素化
Mastra の Client SDK を活用

このガイドに従って、Vite/React プロジェクトに Mastra をスキャフォールドして統合しましょう。

このガイドは、プロジェクトのルート (例: app) で React Router v7 を用いた Vite/React 構成を前提としています。

Mastra をインストール

必要な Mastra パッケージをインストールします：

npm


npm install mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

yarn


yarn add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

pnpm


pnpm add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

bun


bun add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

Mastra を導入する

プロジェクトに Mastra を組み込むには、次の 2 通りの方法があります。

1. ワンライナーを使う

以下のコマンドを実行すると、妥当なデフォルト設定で Weather エージェントを手早く雛形作成できます：


npx mastra@latest init --dir . --components agents,tools --example --llm openai

詳細は mastra init を参照してください。

2. 対話型 CLI を使う

セットアップをカスタマイズしたい場合は、init コマンドを実行し、プロンプトに従ってオプションを選択してください:


npx mastra@latest init

デフォルトでは、mastra init はインストール先として src を提案します。プロジェクトのルート直下で Vite/React を使っている場合（例：app、src/app ではない）、プロンプトで . を入力してください：

package.json に dev と build のスクリプトを追加します:

app

package.json


{
  "scripts": {
    ...
    "dev:mastra": "mastra dev --dir mastra",
    "build:mastra": "mastra build --dir mastra"
  }
}

TypeScript を設定する

プロジェクトのルートにある tsconfig.json ファイルを編集します:

tsconfig.json


{
  ...
  "exclude": ["dist", ".mastra"]
}

API キーを設定する

.env


OPENAI_API_KEY=<your-api-key>

LLM プロバイダーごとに使用する環境変数が異なります。詳しくは Model Capabilities をご覧ください。

.gitignore を更新する

.mastra を .gitignore ファイルに追加します:

.gitignore


.mastra

Mastra Dev Server を起動する

Mastra Dev Server を起動して、エージェントを REST エンドポイントとして公開します。

npm


npm run dev:mastra

起動後、エージェントはローカル環境で利用可能になります。詳細はローカル開発環境を参照してください。

Vite 開発サーバーを起動する

Mastra Dev Server が起動していれば、通常どおり Vite アプリを起動できます。

Mastra クライアントを作成

新しいディレクトリとファイルを作成し、次のサンプルコードを追加します。


mkdir lib
touch lib/mastra.ts

lib/mastra.ts


import { MastraClient } from "@mastra/client-js";
 
export const mastraClient = new MastraClient({
  baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
});

テスト用のルート設定を作成する

設定に新しい route を追加します:

app/routes.ts


import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
export default [
  index("routes/home.tsx"),
  route("test", "routes/test.tsx"),
] satisfies RouteConfig;

テスト用ルートを作成する

新しいルートを作成し、次のサンプルコードを追加します:


touch app/routes/test.tsx

app/routes/test.tsx


import { useState } from "react";
import { mastraClient } from "../../lib/mastra";
 
export default function Test() {
  const [result, setResult] = useState<string | null>(null);
 
  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
 
    const formData = new FormData(event.currentTarget);
    const city = formData.get("city")?.toString();
    const agent = mastraClient.getAgent("weatherAgent");
 
    const response = await agent.generate({
      messages: [{ role: "user", content: `What's the weather like in ${city}?` }]
    });
 
    setResult(response.text);
  }
 
  return (
    <>
      <h1>Test</h1>
      <form onSubmit={handleSubmit}>
        <input name="city" placeholder="Enter city" required />
        <button type="submit">Get Weather</button>
      </form>
      {result && <pre>{result}</pre>}
    </>
  );
}

これでブラウザで /test にアクセスして試せます。

都市に London を入力して送信すると、次のような結果が返ってきます:


The current weather in London is partly cloudy with a temperature of 19.3°C, feeling like 17.4°C. The humidity is at 53%, and there is a wind speed of 15.9 km/h, with gusts up to 38.5 km/h.

次のステップ

Monorepo のデプロイ

Vite/React プロジェクトに Mastra を統合する

Mastra は Vite と統合されており、次のことを容易にします:

柔軟な API を構築して、AI 搭載の機能を提供できる
フロントエンドとバックエンドを単一のコードベースにまとめ、デプロイを簡素化
Mastra の Client SDK を活用

このガイドに従って、Vite/React プロジェクトに Mastra をスキャフォールドして統合しましょう。

このガイドは、プロジェクトのルート (例: app) で React Router v7 を用いた Vite/React 構成を前提としています。

Mastra をインストール

必要な Mastra パッケージをインストールします：

npm


npm install mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

yarn


yarn add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

pnpm


pnpm add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

bun


bun add mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latest

Mastra を導入する

プロジェクトに Mastra を組み込むには、次の 2 通りの方法があります。

1. ワンライナーを使う

以下のコマンドを実行すると、妥当なデフォルト設定で Weather エージェントを手早く雛形作成できます：


npx mastra@latest init --dir . --components agents,tools --example --llm openai

詳細は mastra init を参照してください。

2. 対話型 CLI を使う

セットアップをカスタマイズしたい場合は、init コマンドを実行し、プロンプトに従ってオプションを選択してください:


npx mastra@latest init

package.json に dev と build のスクリプトを追加します:

app

package.json


{
  "scripts": {
    ...
    "dev:mastra": "mastra dev --dir mastra",
    "build:mastra": "mastra build --dir mastra"
  }
}

TypeScript を設定する

プロジェクトのルートにある tsconfig.json ファイルを編集します:

tsconfig.json


{
  ...
  "exclude": ["dist", ".mastra"]
}

API キーを設定する

.env


OPENAI_API_KEY=<your-api-key>

LLM プロバイダーごとに使用する環境変数が異なります。詳しくは Model Capabilities をご覧ください。

.gitignore を更新する

.mastra を .gitignore ファイルに追加します:

.gitignore


.mastra

Mastra Dev Server を起動する

Mastra Dev Server を起動して、エージェントを REST エンドポイントとして公開します。

npm


npm run dev:mastra

起動後、エージェントはローカル環境で利用可能になります。詳細はローカル開発環境を参照してください。

Vite 開発サーバーを起動する

Mastra Dev Server が起動していれば、通常どおり Vite アプリを起動できます。

Mastra クライアントを作成

新しいディレクトリとファイルを作成し、次のサンプルコードを追加します。


mkdir lib
touch lib/mastra.ts

lib/mastra.ts


import { MastraClient } from "@mastra/client-js";
 
export const mastraClient = new MastraClient({
  baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
});

テスト用のルート設定を作成する

設定に新しい route を追加します:

app/routes.ts


import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
export default [
  index("routes/home.tsx"),
  route("test", "routes/test.tsx"),
] satisfies RouteConfig;

テスト用ルートを作成する

新しいルートを作成し、次のサンプルコードを追加します:


touch app/routes/test.tsx

app/routes/test.tsx


import { useState } from "react";
import { mastraClient } from "../../lib/mastra";
 
export default function Test() {
  const [result, setResult] = useState<string | null>(null);
 
  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
 
    const formData = new FormData(event.currentTarget);
    const city = formData.get("city")?.toString();
    const agent = mastraClient.getAgent("weatherAgent");
 
    const response = await agent.generate({
      messages: [{ role: "user", content: `What's the weather like in ${city}?` }]
    });
 
    setResult(response.text);
  }
 
  return (
    <>
      <h1>Test</h1>
      <form onSubmit={handleSubmit}>
        <input name="city" placeholder="Enter city" required />
        <button type="submit">Get Weather</button>
      </form>
      {result && <pre>{result}</pre>}
    </>
  );
}

これでブラウザで /test にアクセスして試せます。

都市に London を入力して送信すると、次のような結果が返ってきます:


The current weather in London is partly cloudy with a temperature of 19.3°C, feeling like 17.4°C. The humidity is at 53%, and there is a wind speed of 15.9 km/h, with gusts up to 38.5 km/h.

次のステップ

Monorepo のデプロイ