Skip to Content
DocsGetting StartedProject Structure

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.

Using the CLI

The Mastra CLI is interactive and allows you to:

  • Choose a directory for Mastra files: Specify where you want the Mastra files to be placed (default is src/mastra).
  • Select components to install: Choose which components you want to include in your project:
    • Agents
    • Tools
    • Workflows
  • Select a default LLM provider: Choose from supported providers like OpenAI, Anthropic, Groq, Google or Cerebras.
  • Include example code: Decide whether to include example code to help you get started.
  • Install Mastra docs MCP server: Make your AI IDE a Mastra expert

Example Project Structure

Assuming you select all components and include example code, your project structure will look like this:

        • agent-name.ts
        • tool-name.ts
        • workflow-name.ts
      • index.ts
  • .env
  • package.json
  • tsconfig.json

Top-level Folders

FolderDescription
src/mastraCore application folder
src/mastra/agentsAgent configurations and definitions
src/mastra/toolsCustom tool definitions
src/mastra/workflowsWorkflow definitions

Top-level Files

FileDescription
src/mastra/index.tsMain configuration file for Mastra
.envEnvironment variables
package.jsonNode.js project metadata, scripts, and dependencies
tsconfig.jsonTypeScript compiler configuration