Skip to main content

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.

warning

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

  1. Install the required Mastra packages:

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

  2. To integrate Mastra into your project, you have two options:

    • 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.

    • 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"
      }
    }

  3. Modify the tsconfig.json file in your project root:

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

  4. Setup your API key in a .env file:

    .env
    OPENAI_API_KEY=<your-api-key>

  5. Add .mastra and .vercel to your .gitignore file:

    .gitignore
    .mastra
    .vercel

  6. 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.

  7. 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.

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

  9. Create an actions directory:

    mkdir src/actions

  10. 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;
        },
      }),
    };

  11. 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>}
        </>
      );
    };

  12. 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!

Next Steps​

On this page