Mastra Project Structure
Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference
Published: 2026-05-10 · Source: crawler_authoritative
Tình huống
Documentation for developers creating new Mastra projects, explaining the default file and folder structure generated by the create-mastra CLI command.
Insight
Mastra is a framework that is unopinionated about project organization. The create-mastra command generates a sensible default structure, but developers are free to adapt it. The core code lives in src/mastra/ with subdirectories for agents, tools, workflows, scorers, and MCP servers. The src/mastra/index.ts serves as the central entry point for configuring and initializing Mastra. Optional folders include src/mastra/mcp for custom MCP servers to share tools with external agents, src/mastra/scorers for evaluating agent performance, and src/mastra/public for assets copied to .build/output at runtime. Top-level configuration files include .env.example as a template for API keys, package.json for dependencies and npm scripts, and tsconfig.json for TypeScript path aliases and compiler settings. The documentation recommends using predefined files as templates, duplicating and adapting them to quickly create new agents, tools, and workflows.
Hành động
To create a new Mastra project, run the create-mastra CLI command. The CLI generates src/mastra/agents/, src/mastra/tools/, src/mastra/workflows/, and src/mastra/scorers/ directories with example files. Copy src/mastra/.env.example to .env and add your model provider API keys. Configure TypeScript in tsconfig.json with path aliases pointing to your source directories. Extend the project by duplicating example files and modifying them to create custom agents, tools, workflows, or scorers.
Nội dung gốc (Original)
Project structure
Your new Mastra project, created with the create mastra command, comes with a predefined set of files and folders to help you get started.
Mastra is a framework, but it’s unopinionated about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you’re free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
Default project structure
A project created with the create mastra command looks like this:
src/
├── mastra/
│ ├── agents/
│ │ └── weather-agent.ts
│ ├── tools/
│ │ └── weather-tool.ts
│ ├── workflows/
│ │ └── weather-workflow.ts
│ ├── scorers/
│ │ └── weather-scorer.ts
│ └── index.ts
├── .env.example
├── package.json
└── tsconfig.jsonTip: Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
Folders
Folders organize your agent’s resources, like agents, tools, and workflows.
| Folder | Description |
|---|---|
src/mastra | Entry point for all Mastra-related code and configuration. |
src/mastra/agents | Define and configure your agents - their behavior, goals, and tools. |
src/mastra/workflows | Define multi-step workflows that orchestrate agents and tools together. |
src/mastra/tools | Create reusable tools that your agents can call |
src/mastra/mcp | (Optional) Implement custom MCP servers to share your tools with external agents |
src/mastra/scorers | (Optional) Define scorers for evaluating agent performance over time |
src/mastra/public | (Optional) Contents are copied into the .build/output directory during the build process, making them available for serving at runtime |
Top-level files
Top-level files define how your Mastra project is configured, built, and connected to its environment.
| File | Description |
|---|---|
src/mastra/index.ts | Central entry point where you configure and initialize Mastra. |
.env.example | Template for environment variables - copy and rename to .env to add your secret model provider keys. |
package.json | Defines project metadata, dependencies, and available npm scripts. |
tsconfig.json | Configures TypeScript options such as path aliases, compiler settings, and build output. |
Next steps
- Read more about Mastra’s features.
- Integrate Mastra with your frontend framework: Next.js, React, or Astro.
- Build an agent from scratch following one of our guides.
- Watch conceptual guides on our YouTube channel and subscribe!
Liên kết
- Nền tảng: Dev Framework · Mastra
- Nguồn: https://mastra.ai/docs/getting-started/project-structure
Xem thêm: