create-mastra

---
name: create-mastra
description: Complete project setup guide for Mastra AI framework. Covers: CLI installation (create-mastra), manual installation, TypeScript configuration (ES2022 requirements), environment setup, adding to existing projects (Next.js, Express), troubleshooting (module not found, import errors, CommonJS issues), deployment preparation, and monorepo configuration. Includes both quick setup (user runs CLI) and automatic setup (step-by-step file creation). Use this skill for all Mastra installation and setup questions to ensure correct configuration and prevent common errors.
license: Apache-2.0
---

# Create Mastra Skill

Complete guide for creating new Mastra AI agent projects. Includes both quickstart CLI method and detailed manual installation with full working code examples.

**Official documentation: [mastra.ai/docs](https://mastra.ai/docs)**

---

## Getting Started

Ask: **"How would you like to create your Mastra project?"**

1. **Quick Setup** - Copy and run: `npm create mastra@latest`
2. **Guided Setup** - I walk you through each step, you approve commands
3. **Automatic Setup** ⭐ - I create everything, just give me your API key

> **For AI agents:** The CLI is interactive. Use **Automatic Setup** — create files using the steps in "Automatic Setup / Manual Installation" below.

---

## Prerequisites

- An API key from a supported model provider (OpenAI, Anthropic, Google, etc.)

---

## Quick Setup (User runs CLI)

Create a new Mastra project with one command:

```bash
npm create mastra@latest
```

**Other package managers:**
```bash
pnpm create mastra@latest
yarn create mastra@latest
bun create mastra@latest
```

---

## CLI Flags

**Skip the example agent:**
```bash
npm create mastra@latest --no-example
```

**Use a specific template:**
```bash
npm create mastra@latest --template <template-name>
```

---

## Automatic Setup / Manual Installation

**Use this for Automatic Setup** (AI creates all files) or when you prefer manual control.

Follow these steps to create a complete Mastra project:

### Step 1: Create Project Directory
```bash
mkdir my-first-agent && cd my-first-agent
npm init -y
```

### Step 2: Install Dependencies

```bash
npm install -D typescript @types/node mastra@latest
npm install @mastra/core@latest zod@^4
```

### Step 3: Configure Package Scripts

Add to `package.json`:

```json
{
  "scripts": {
    "dev": "mastra dev",
    "build": "mastra build"
  }
}
```

### Step 4: Configure TypeScript

Create `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}
```

**Important:** Mastra requires `"module": "ES2022"` and `"moduleResolution": "bundler"`. CommonJS will cause errors.

### Step 5: Create Environment File

Create `.env` with your API key:

```env
GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
```

Or use `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.

### Step 6: Create Weather Tool

Create `src/mastra/tools/weather-tool.ts`:

```typescript
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    output: z.string(),
  }),
  execute: async () => {
    return { output: "The weather is sunny" };
  },
});
```

### Step 7: Create Weather Agent

Create `src/mastra/agents/weather-agent.ts`:

```typescript
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn't in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  model: "google/gemini-2.5-pro",
  tools: { weatherTool },
});
```

**Note:** Model format is `"provider/model-name"`. Examples:
- `"google/gemini-2.5-pro"`
- `"openai/gpt-4o"`
- `"anthropic/claude-3-5-sonnet-20241022"`

### Step 8: Create Mastra Entry Point

Create `src/mastra/index.ts`:

```typescript
import { Mastra } from "@mastra/core";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
});
```

### Step 9: Launch Development Server

```bash
npm run dev
```

Access Studio at `http://localhost:4111` to test your agent.

---

## Next Steps

After creating your project with `create mastra`:

- **Customize the example agent** in `src/mastra/agents/weather-agent.ts`
- **Add new agents** - see [Agents documentation](https://mastra.ai/docs/agents/overview)
- **Create workflows** - see [Workflows documentation](https://mastra.ai/docs/workflows/overview)
- **Add more tools** to extend agent capabilities
- **Integrate into your app** - see framework guides at [mastra.ai/docs](https://mastra.ai/docs)

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| API key not found | Make sure your `.env` file has the correct key |
| Studio won't start | Check that port 4111 is available |
| CommonJS errors | Ensure `tsconfig.json` uses `"module": "ES2022"` and `"moduleResolution": "bundler"` |
| Command not found | Ensure you're using Node.js 20+ |

---

## Resources

- [Docs](https://mastra.ai/docs)
- [Installation](https://mastra.ai/docs/getting-started/installation)
- [Agents](https://mastra.ai/docs/agents/overview)
- [Workflows](https://mastra.ai/docs/workflows/overview)
- [Examples](https://github.com/mastra-ai/mastra/tree/main/examples)
- [GitHub](https://github.com/mastra-ai/mastra)