@mastra/core

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