Project Structure and Organization
This page provides a guide for organizing folders and files in Mastra. Mastra is a modular framework, and you can use any of the modules separately or together.
You could write everything in a single file (as we showed in the quick start), or separate each agent, tool, and workflow into their own files. We don’t enforce a specific folder structure, but we do recommend some best practices, and the CLI will scaffold a project with a sensible structure.
Using the CLI
When you run mastra init, it will create the files and folders listed below:
Top-level Folders
| Folder | Description |
|---|---|
mastra | Core application folder |
mastra/agents | Agent configurations and definitions |
mastra/blueprints | Workflow blueprint definitions |
mastra/tools | Custom tool definitions |
mastra/vector-configs | Vector database configurations |
mastra/integrations | Integration configurations |
Top-level Files
| File | Description |
|---|---|
mastra/index.ts | Main configuration file for Mastra |
.env.development | Development environment variables |