# 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:

**npm**:

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

**pnpm**:

```sh
pnpm dlx create-mastra@latest --template template-name
```

**Yarn**:

```sh
yarn dlx create-mastra@latest --template template-name
```

**Bun**:

```sh
bun x create-mastra@latest --template template-name
```

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

### Setup Process

After installation:

1. **Navigate to project directory**:

   ```bash
   cd your-project-name
   ```

2. **Configure environment variables**:

   ```bash
   cp .env.example .env
   ```

   Edit `.env` with required API keys as documented in the template's README.

3. **Install dependencies** (if not done automatically):

   **npm**:

   ```sh
   npm install
   ```

   **pnpm**:

   ```sh
   pnpm install
   ```

   **Yarn**:

   ```sh
   yarn install
   ```

   **Bun**:

   ```sh
   bun install
   ```

4. **Start development server**:

   **npm**:

   ```sh
   npm run dev
   ```

   **pnpm**:

   ```sh
   pnpm run dev
   ```

   **Yarn**:

   ```sh
   yarn dev
   ```

   **Bun**:

   ```sh
   bun run dev
   ```

### Template structure

All templates follow this standardized structure:

```text
your-template/
├── src/
│   └── mastra/
│       ├── agents/       # Agent definitions
│       ├── tools/        # Tool definitions
│       ├── workflows/    # Workflow definitions
│       └── index.ts      # Main Mastra config
├── .env.example          # Required environment variables
├── package.json
├── tsconfig.json
└── README.md
```

## 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](https://mastra.ai/docs/community/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.