Setting Up Your First Mastra Project

Set up a working TypeScript environment for your customer support assistant using the Mastra CLI, configure your API keys, and run Mastra Studio locally.

Previous lesson: Mastra Overview: What Is Mastra? | Next lesson: Building Your First Mastra Agent

Prerequisites and Project Initialization

Before you run any commands, make sure you have Node.js version 22.18.0 or later installed on your computer. You can check your version by running node -v in your terminal.

The fastest way to scaffold a new project is with the Mastra CLI. Open your terminal, navigate to the directory where you store your projects, and run this command:

bash
Copy

The interactive prompt will ask you for a project name. Name it customer-support-agent. The CLI will create a new directory, initialize a package.json file, set up TypeScript, and install the required dependencies.

If you prefer to initialize the directory by hand instead of using the generator, you can install the packages manually:

bash
Copy

Mastra requires ECMAScript modules. The package.json file must contain "type": "module" so Node.js loads your TypeScript files correctly through the Mastra development server.

Common Mistake: Forgetting to set "type": "module" in package.json causes module resolution errors when importing @mastra/core. Verify that this field is present before proceeding.

If you set the project up by hand, you also need a tsconfig.json file. The npm create mastra@latest command generates one for you, so the generator is the easier path for beginners.

Later lessons run small TypeScript test scripts with tsx. Install it as a development dependency now, whichever setup path you chose:

bash
Copy

Project Structure Overview

A standard Mastra project isolates framework code inside a dedicated folder. This structure keeps your application organized as you add agents, tools, and workflows throughout this course.

Think of the src/mastra directory like an air traffic control tower. The control tower houses the central registry, while the runways and gates hold your specific agents, tools, and workflows.

Your project should follow this file tree:

text
Copy

Here is what each item does:

• src/mastra/index.ts: The main entry point. You export an instance of the Mastra class from this file.
• src/mastra/agents/: Directory where you define your agent instances and instructions.
• src/mastra/tools/: Directory where you define custom tools using schemas.
• src/mastra/workflows/: Directory where you build deterministic, step-by-step processes.
• .env: A plain text file that contains your secrets and API keys.

Quick Insight: Mastra looks for src/mastra/index.ts by default when starting the local dev server. Keeping this entry point clean ensures the CLI can automatically discover all registered resources.

Configuring API Keys and Environment Variables

Mastra delegates model execution to large language model providers. For this course, you will use OpenAI models like openai/gpt-5-mini.

Create a file named .env in the root of your project:

bash
Copy

Add your provider keys inside .env:

env
Copy

If you plan to test other providers later, you can also include their keys in the same file:

env
Copy

npm run dev loads the variables in .env automatically, so the dev server and Mastra Studio need no extra setup. You do not need to install dotenv.

Standalone test scripts are different. When you run a script with tsx in later lessons, .env is not loaded on its own, so those commands include the --env-file=.env flag.

Pro Tip: Never commit .env to version control. Add .env to your .gitignore file immediately so your secret keys remain private.

The Minimal Mastra Entry Point

To start the development server without errors, you need a valid entry point file that exports a Mastra instance.

Create the file src/mastra/index.ts and paste the following complete code block into it:

ts
Copy

This snippet initializes a Mastra instance with empty registries for agents and workflows. In the upcoming lessons, you will import and register your customer support agent, custom order lookup tools, and ticket workflows directly into this object.

Try This: Open your package.json file and verify that you have a dev script defined. It should look like this:

json
Copy

If the script is missing, add it to your scripts block so you can start Mastra using standard npm commands.

Launching the Development Server and Mastra Studio

Now you are ready to boot up the environment. Run the development command in your terminal:

bash
Copy

The CLI starts the local server and outputs two important URLs:

1. Mastra Studio: http://localhost:4111
2. Swagger API Documentation: http://localhost:4111/swagger-ui

Open http://localhost:4111 in your web browser. Mastra Studio is a visual dashboard that connects directly to your local codebase. From Studio, you can:

• Inspect registered agents and chat with them in real time.
• Execute tools in isolation with custom inputs.
• Step through workflow runs and view execution traces.
• Compare prompts and test alternative models.

The Swagger interface at http://localhost:4111/swagger-ui exposes auto-generated REST endpoints for every agent and workflow registered on your Mastra instance. This means you can integrate your Mastra backend with web hooks, frontend apps, or external services without writing custom HTTP handlers.

Quick Challenge: While npm run dev is running, visit http://localhost:4111/swagger-ui and check the OpenAPI schema generated by your empty Mastra instance.

Try It Yourself

1. Run node -v to confirm you have Node.js 22.18.0 or later.
2. Initialize your project folder and verify that package.json contains "type": "module".
3. Add a valid OPENAI_API_KEY to your .env file.
4. Save the minimal src/mastra/index.ts file provided in this lesson.
5. Run npm run dev and navigate to http://localhost:4111 to confirm that Mastra Studio opens cleanly.

In the next lesson, Building Your First Mastra Agent, you will define your first support agent with custom system instructions and test it inside Mastra Studio.