Overview

This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.

Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:

Working examples - Complete, functional Mastra applications
Best practices - Proper project structure and coding conventions
Educational resources - Learn Mastra patterns through real implementations
Quickstarts - Bootstrap projects faster than building from scratch

Using templates

Installation

Install a template using the create-mastra command:

bash

npx create-mastra@latest --template template-name

This creates a complete project with all necessary code and configuration.

Setup Process

After installation:

Navigate to project directory:
bash
```
cd your-project-name
```
Configure environment variables:
bash
```
cp .env.example .env
```
Edit .env with required API keys as documented in the template's README.
Install dependencies (if not done automatically):
bash
```
npm install
```
Start development server:
bash
```
npm run dev
```

Template Structure

All templates follow this standardized structure:

Creating templates

Requirements

Templates must meet these technical requirements:

Project Structure

Mastra code location: All Mastra code must be in src/mastra/ directory
Component organization:
- Agents: src/mastra/agents/
- Tools: src/mastra/tools/
- Workflows: src/mastra/workflows/
- Main config: src/mastra/index.ts

TypeScript Configuration

Use the standard Mastra TypeScript configuration:

json

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

Environment Configuration

Include a .env.example file with all required environment variables:

bash

# LLM provider API keys (choose one or more)
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here

# Other service API keys as needed
OTHER_SERVICE_API_KEY=your_api_key_here

Code Standards

LLM Provider

We recommend using OpenAI, Anthropic, or Google model providers for templates. Choose the provider that best fits your use case:

typescript

import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  name: 'example-agent',
  model: 'openai/gpt-5.4', // or other provider strings
  instructions: 'Your agent instructions here',
})

Compatibility Requirements

Templates must be:

Single projects - Not monorepos with multiple applications
Framework-free - No Next.js, Express, or other web framework boilerplate
Mastra-focused - Demonstrate Mastra functionality without additional layers
Mergeable - Structure code for seamless integration into existing projects
Node.js compatible - Support Node.js v22.13.0 and later
ESM modules - Use ES modules ("type": "module" in package.json)

Documentation Requirements

README Structure

Every template must include a comprehensive README:

markdown

# Template Name

Brief description of what the template demonstrates.

## Overview

Detailed explanation of the template's functionality and use case.

## Setup

1. Copy `.env.example` to `.env` and fill in your API keys
2. Install dependencies: `npm install`
3. Run the project: `npm run dev`

## Environment variables

- `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
- `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
- `OTHER_API_KEY`: Description of what this key is for

## Usage

Instructions on how to use the template and examples of expected behavior.

## Customization

Guidelines for modifying the template for different use cases.

Code Comments

Include clear comments explaining:

Complex logic or algorithms
API integrations and their purpose
Configuration options and their effects
Example usage patterns

Quality Standards

Templates must demonstrate:

Code quality - Clean, well-commented, maintainable code
Error handling - Proper handling for external APIs and user inputs
Type safety - Full TypeScript typing with Zod validation
Testing - Verified functionality with fresh installations

For information on contributing your own templates to the Mastra ecosystem, see the Contributing Templates guide in the community section.

:::info

Templates provide an excellent way to learn Mastra patterns and accelerate development. Contributing templates helps the entire community build better AI applications.

:::

Reference: LLM provider API keys (choose one or more) | Templates