Skip to Content
DocsFrameworksWith Astro

Integrate Mastra in your Astro project

Mastra integrates with Astro, 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 Astro’s built-in Actions  or Server Endpoints  for efficient server-client workflows

Use this guide to scaffold and integrate Mastra with your Astro project.

⚠️

This guide assumes you’re using Astro’s Actions with React and the Vercel adapter.

Install Mastra

Install the required Mastra packages:

npm install mastra@latest @mastra/core@latest @mastra/libsql@latest

Integrate 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 --default

See 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 init

Add the dev and build scripts to package.json:

package.json
{
  "scripts": {
    ...
    "dev:mastra": "mastra dev",
    "build:mastra": "mastra build"
  }
}

Configure TypeScript

Modify the tsconfig.json file in your project root:

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

Set Up API Key

.env
OPENAI_API_KEY=<your-api-key>

Update .gitignore

Add .mastra to your .gitignore file:

.gitignore
.mastra

Update the Mastra Agent

Astro uses Vite, which accesses environment variables via import.meta.env rather than process.env. As a result, the model constructor must explicitly receive the apiKey from the Vite environment like this:

src/mastra/agents/weather-agent.ts
- import { openai } from "@ai-sdk/openai";
+ import { createOpenAI } from "@ai-sdk/openai";
 
+ const openai = createOpenAI({
+   apiKey: import.meta.env?.OPENAI_API_KEY,
+   compatibility: "strict"
+ });

More configuration details are available in the AI SDK docs. See Provider Instance  for more information.

Start the Mastra Dev Server

Start the Mastra Dev Server to expose your agents as REST endpoints:

npm run dev:mastra

Once running, your agents are available locally. See Local Development Environment for more information.

Start Astro Dev Server

With the Mastra Dev Server running, you can start your Astro site in the usual way.

Create Actions Directory

mkdir src/actions

Create Test Action

Create a new Action, and add the example code:

touch src/actions/index.ts
src/actions/index.ts
import { defineAction } from "astro:actions";
import { z } from "astro:schema";
 
import { mastra } from "../mastra";
 
export const server = {
  getWeatherInfo: defineAction({
    input: z.object({
      city: z.string()
    }),
    handler: async (input) => {
      const city = input.city;
      const agent = mastra.getAgent("weatherAgent");
 
      const result = await agent.generate(`What's the weather like in ${city}?`);
 
      return result.text;
    }
  })
};

Create Test Form

Create a new Form component, and add the example code:

touch src/components/form.tsx
src/components/form.tsx
import { actions } from "astro:actions";
import { useState } from "react";
 
export const Form = () => {
  const [result, setResult] = useState<string | null>(null);
 
  async function handleSubmit(formData: FormData) {
    const city = formData.get("city")!.toString();
    const { data } = await actions.getWeatherInfo({ city });
 
    setResult(data || null);
  }
 
  return (
    <>
      <form action={handleSubmit}>
        <input name="city" placeholder="Enter city" required />
        <button type="submit">Get Weather</button>
      </form>
      {result && <pre>{result}</pre>}
    </>
  );
};

Create Test Page

Create a new Page, and add the example code:

touch src/pages/test.astro
src/pages/test.astro
---
import { Form } from '../components/form'
---
 
<h1>Test</h1>
<Form client:load />

You can now navigate to /test in your browser to try it out.

Submitting London as the city would return a result similar to:

Agent response: The current weather in London is as follows:

- **Temperature:** 12.9°C (Feels like 9.7°C)
- **Humidity:** 63%
- **Wind Speed:** 14.7 km/h
- **Wind Gusts:** 32.4 km/h
- **Conditions:** Overcast

Let me know if you need more information!
With Next.jsWith Express