Integrate Mastra in your Vite/React project
Mastra integrates with Vite, making it easy to:
- Build flexible APIs to serve AI-powered features
- Simplify deployment with a unified codebase for frontend and backend
- Take advantage of Mastra’s Client SDK
Use this guide to scaffold and integrate Mastra with your Vite/React project.
This guide assumes you’re using Vite/React with React Router v7 at the root of
your project, e.g., app.
Install Mastra
Install the required Mastra packages:
npm
npm install mastra@latest @mastra/core@latest @mastra/libsql@latest @mastra/client-js@latestIntegrate Mastra
To integrate Mastra into your project, you have two options:
1. Use the One-Liner
Run the following command to quickly scaffold the default Weather agent with sensible defaults:
npx mastra@latest init --dir . --components agents,tools --example --llm openaiSee mastra init for more information.
2. Use the Interactive CLI
If you prefer to customize the setup, run the init command and choose from the options when prompted:
npx mastra@latest initBy default, mastra init suggests src as the install location. If you’re using Vite/React at the root of your project (e.g., app, not src/app), enter . when prompted:
Add the dev and build scripts to package.json:
app
{
"scripts": {
...
"dev:mastra": "mastra dev --dir mastra",
"build:mastra": "mastra build --dir mastra"
}
}Configure TypeScript
Modify the tsconfig.json file in your project root:
{
...
"exclude": ["dist", ".mastra"]
}Set Up API Keys
OPENAI_API_KEY=<your-api-key>Each LLM provider uses a different env var. See Model Capabilities for more information.
Update .gitignore
Add .mastra to your .gitignore file:
.mastraStart the Mastra Dev Server
Start the Mastra Dev Server to expose your agents as REST endpoints:
npm
npm run dev:mastraOnce running, your agents are available locally. See Local Development Environment for more information.
Start Vite Dev Server
With the Mastra Dev Server running, you can start your Vite app in the usual way.
Create Mastra Client
Create a new directory and file. Then add the example code:
mkdir lib
touch lib/mastra.tsimport { MastraClient } from "@mastra/client-js";
export const mastraClient = new MastraClient({
baseUrl: import.meta.env.VITE_MASTRA_API_URL || "http://localhost:4111",
});Create Test Route Config
Add new route to the config:
import { type RouteConfig, index, route } from "@react-router/dev/routes";
export default [
index("routes/home.tsx"),
route("test", "routes/test.tsx"),
] satisfies RouteConfig;Create Test Route
Create a new Route, and add the example code:
touch app/routes/test.tsximport { 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>}
</>
);
}You can now navigate to
/testin your browser to try it out.
Submitting London as the city would return a result similar to:
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.