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 easy to navigate.
Default project structureDirect link to 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.json
Tip - Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
FoldersDirect link to 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 filesDirect link to 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 stepsDirect link to 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!