Project Structure

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

Example Project Structure

A default project created with the CLI looks like this:

• src
  • mastra
    • agents
      • agent-name.ts
    • tools
      • tool-name.ts
    • workflows
      • workflow-name.ts
    • index.ts
• .env
• package.json
• tsconfig.json

Top-level Folders

Top-level Files