Mastra Docs

Mastra Documentation Guidelines

Use this skill when you create or update Mastra docs. Keep the docs clear and consistent. Follow the most specific AGENTS.md for the area you change.

Styleguides

Start with references/STYLEGUIDE.md for all docs. Then use the guide that matches the content:

• references/DOC.md - General docs that do not fit the categories below
• Choose the right guide for the file's content:
• references/GUIDE_QUICKSTART.md - Quickstarts that help readers get working fast with a specific library or framework
• references/GUIDE_TUTORIAL.md - Tutorials that teach readers how to build something with Mastra
• references/GUIDE_INTEGRATION.md - Integration guides for using Mastra with an external library or ecosystem
• references/GUIDE_DEPLOYMENT.md - Deployment guides for shipping a Mastra app to a platform
• references/REFERENCE.md - Reference and API docs

Linting

Use these tools to keep docs consistent:

• prettier - Formats files and code blocks. This is the base linting layer.
• remark - Checks markdown issues like heading levels, list styles, and formatting consistency. This is the middle layer.
• vale - Checks grammar, style, and wording. This is the top layer.

Run these commands in docs/:

• npm run format - Format files with Prettier
• npm run lint:remark - Check markdown with Remark
• npm run lint:vale:ai - Check prose with Vale using the error alert level

DOC styleguide

Read STYLEGUIDE.md first.

Use this file for general docs pages. There are two page types.

Overview pages

Use for category landing pages like agents/overview.mdx or memory/overview.mdx.

What to do:

• introduce the category
• list the main sub-topics
• link to the standard pages in the category
• help the reader decide where to start
• keep it broad, not deep

Use this shape:

---
title: '$CATEGORY overview'
description: 'One to two sentences describing what this topic covers.'
packages:
  - '@mastra/core'
  - '@mastra/<module>'
---

# $CATEGORY overview

One to two sentence intro. Say what the category does and why it matters.

Optional image or diagram.

- [Sub-topic A](/docs/$CATEGORY/sub-topic-a): one sentence on what it does
- [Sub-topic B](/docs/$CATEGORY/sub-topic-b): one sentence on what it does

## When to use $CATEGORY

Short paragraph or short list of use cases.

## Get started

Point to the best starting page.

## Optional sections

Add short H2 sections only for category-wide topics like storage, debugging, or shared config.

## Next steps

- [Sub-topic A](/docs/$CATEGORY/sub-topic-a)
- [Sub-topic B](/docs/$CATEGORY/sub-topic-b)
- [API reference](/reference/$CATEGORY/$CLASS)

Rules:

• title must be $CATEGORY overview
• opening paragraph must be one or two sentences
• every standard page in the category should be linked from the page
• if one sub-topic needs more than two paragraphs, move it to its own standard page
• end with Next steps, not Related

Standard pages

Use for every non-overview page in the category.

What to do:

• teach one concept
• give enough context to use it
• show working code
• link to the API reference

Use this shape:

````mdx --- title: '$FEATURE | $CATEGORY' description: 'One sentence describing what the reader will learn.' packages:

• '@mastra/core'
• '@mastra/<module>'

---

$FEATURE

One to two sentence intro. Say what the feature is and why to use it.

When to use $FEATURE

Include this when the reader may need help choosing this feature.

Quickstart

Show the shortest working example.

```typescript title="src/mastra/<path>.ts" import { Thing } from '@mastra/core/<module>';

const thing = new Thing({ id: 'my-thing', // minimal config });

## Core sections

Use one or more H2 sections. Each section should have:

1. one or two short paragraphs
2. a TypeScript example
3. a note linking to the API reference when needed

// Code showing this concept

:::note
Visit [ClassName reference](/reference/$CATEGORY/<class>) for the full config.
:::

## Related

- [Related page 1](/docs/$CATEGORY/page-1)
- [Related page 2](/docs/$CATEGORY/page-2)
- [API reference](/reference/$CATEGORY/<class>)

Rules:

• title must be $FEATURE | $CATEGORY
• opening paragraph must be one or two sentences
• quickstart should be the shortest copy-pasteable working example
• use line highlighting when it helps point out important lines
• use TypeScript fenced code blocks with a title for file paths
• use npm2yarn on bash install blocks
• use Tabs only for mutually exclusive choices
• use Steps and StepItem when order matters
• use note for API reference links
• use tip and warning sparingly
• end with Related
• keep one concept per page; split the page if it grows past three H2 subsections

Deployment guide styleguide

Read STYLEGUIDE.md first.

Use this file for deployment guides.

Goal:

• assume the reader already has a working Mastra app
• show how to deploy it to one platform
• cover install, config, deploy, and platform-specific concerns

Use this shape:

````mdx --- title: 'Deploy Mastra to $PLATFORM | Deployment' description: 'Learn how to deploy a Mastra application to $PLATFORM' ---

import Steps from '@site/src/components/Steps'; import StepItem from '@site/src/components/StepItem';

Deploy Mastra to $PLATFORM

One or two sentences on what the deployer does and how it works. Link to the platform docs.

:::note Clarify scope. Say what this guide covers and what it does not. Link to alternatives if the reader may be in the wrong guide. :::

Before you begin

You'll need a Mastra application and a $PLATFORM account.

Call out platform constraints that affect config, such as ephemeral filesystems, cold starts, or storage requirements.

Installation

Add the deployer package:

```bash npm2yarn npm install @mastra/deployer-$PLATFORM@latest

Import the deployer and set it in the Mastra config:

import { Mastra } from '@mastra/core'; import { $PlatformDeployer } from '@mastra/deployer-$PLATFORM';

export const mastra = new Mastra({ deployer: new $PlatformDeployer(), });

## Deploy

<Steps>
<StepItem>

Push or connect the code to the platform.

</StepItem>
<StepItem>

Trigger the deploy. Show the command to run or the action to take.

:::note
Remind the reader to set environment variables.
:::

</StepItem>
<StepItem>

Verify the deployment with a URL or command.

</StepItem>
</Steps>

## Optional overrides

Briefly describe config options. Link to the deployer reference for the full list.

## $PLATFORM_SPECIFIC_CONCERN

Explain platform-specific gotchas, such as observability flush or cold start mitigation. Add code if the reader needs to change code to handle it.

// Code addressing the platform concern

:::warning
Explain the limitation and link to alternatives when needed.
:::

## Related

- [$PlatformDeployer reference](/reference/deployer/$PLATFORM)
- [Deployment overview](/docs/deployment/overview)
- [Related guide or doc](/docs/category/page)

Rules:

• frontmatter title must be Deploy Mastra to $PLATFORM | Deployment
• H1 must match the title without the category suffix
• add the note after the intro when the guide covers only one deployment path and alternatives exist
• Before you begin must require a working Mastra app and a platform account
• call out platform constraints that affect configuration
• Installation must include both package install and Mastra config
• use bash npm2yarn on install commands
• use <Steps> for the deploy flow
• keep verification as the last StepItem, not a separate H2
• add platform-specific H2 sections after Deploy when needed
• include code and warning blocks for platform limitations when needed
• end with Related
• do not add a congratulations section

Integration guide styleguide

Read STYLEGUIDE.md first.

Use this file for integration guides.

Goal:

• document how to use Mastra with one external library or ecosystem
• organize by feature area, not by step order
• make each section self-contained so the reader can jump to it

Use this shape:

````mdx --- title: 'Using $LIBRARY | $CATEGORY' description: 'Learn how Mastra integrates with $LIBRARY and how to use it in your project' ---

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Using $LIBRARY

One or two sentences on what the library is and what the guide covers. Link to the official docs.

:::note Link to migration guides or version notes when needed. :::

:::tip Link to live examples or related quickstarts. :::

Getting started

Briefly explain what the integration package provides and which features it enables. List the key hooks, functions, or APIs it connects to, with links to official docs.

Install the required packages:

```bash npm2yarn npm install @mastra/package@latest other-package

One sentence confirming the reader is ready to continue.

## $FEATURE_AREA_1

Brief explanation of the feature area. Add a short list linking to the approaches below.

- [$APPROACH_A](#approach-a)
- [$APPROACH_B](#approach-b)

### $APPROACH_A

Context sentence.

<Tabs>
  <TabItem value="option-1" label="Option 1">

Brief explanation of this option.

// Complete code for option 1

  </TabItem>
  <TabItem value="option-2" label="Option 2">

Brief explanation of this option.

// Complete code for option 2

  </TabItem>
</Tabs>

### $APPROACH_B

Context sentence.

<Tabs>
  <TabItem value="option-1" label="Option 1">

Code and explanation for option 1.

  </TabItem>
  <TabItem value="option-2" label="Option 2">

Code and explanation for option 2.

  </TabItem>
</Tabs>

### $FRONTEND_HOOK

After the backend setup, show how to connect the frontend. Include a complete code example and highlight the key line.

// Frontend code connecting to the backend

## $FEATURE_AREA_2

Brief explanation of this feature area and when to use it.

### $CONCEPT_REFERENCE

Use a table or list for types, events, or data structures the reader needs to look up.

| Type     | Source      | Description        |
| -------- | ----------- | ------------------ |
| `type-a` | Component A | What it represents |
| `type-b` | Component B | What it represents |

### $PATTERN_1

Context for the pattern.

<Tabs>
  <TabItem value="backend" label="Backend">

// Backend code

  </TabItem>
  <TabItem value="frontend" label="Frontend">

// Frontend code

  </TabItem>
</Tabs>

:::tip
Explain naming conventions, key points, or common gotchas.
:::

### $PATTERN_2

Same structure as above.

For more details, see [Related doc](/docs/category/page).

## Recipes

### $RECIPE_1

Brief description. Link to reference docs or utilities.

### $RECIPE_2

Context sentence.

<Tabs>
  <TabItem value="backend" label="Backend">

// Backend code

  </TabItem>
  <TabItem value="frontend" label="Frontend">

// Frontend code

  </TabItem>
</Tabs>

Key points:

- Point 1
- Point 2

For a complete implementation, see the [example-name example](https://link-to-example).

Rules:

• frontmatter title must be Using $LIBRARY | $CATEGORY
• H1 must be Using $LIBRARY
• after the intro, use note for migration or version notes and tip for live examples or related quickstarts when needed
• Getting started must install the integration package, explain what it provides, and list the main APIs it connects to
• keep Getting started short; this is not a tutorial
• H2 sections must be feature areas, not sequential steps
• each H3 must be a self-contained approach or pattern
• when a pattern has both server and client code, use Tabs with Backend and Frontend
• when there are multiple backend approaches, use Tabs with clear labels like Mastra Server or Next.js
• show complete working code in tabs
• use tables for types, events, and data structures in the relevant feature area
• put standalone patterns at the end under Recipes
• each recipe should include brief context, code, key points, and a link to a complete implementation when applicable
• after complex examples, add a Key points: list with one-sentence bullets
• link to live example repositories instead of duplicating entire apps
• do not add Next steps or Related
• use npm2yarn on install commands

Quickstart guide styleguide

Read STYLEGUIDE.md first.

Use this file for quickstarts.

Goal:

• get the reader to a working result fast
• focus on one setup or integration
• produce something the reader can run or interact with

Use this shape:

````mdx --- title: '$TECHNOLOGY | $CATEGORY' description: '$VERB with Mastra and $TECHNOLOGY' ---

$ACTION_ORIENTED_TITLE

One sentence on what the reader will build and which technologies are used. Link to external docs for unfamiliar technologies.

Before you begin

• Prerequisite 1
• Prerequisite 2

Create a new $TECHNOLOGY app (optional)

Brief context.

```bash npm2yarn npx create-something@latest my-project

One sentence on what the command did.

## Initialize Mastra

Brief context.

npx mastra@latest init

Explain what was created and which files matter next.

## $STEP_3

Brief context.

npm install @mastra/package@latest

## $STEP_N

Brief context on what this code does.

// Complete, working code the reader can copy

One or two sentences on the key parts. Focus on why, not what.

## Test your $THING

1. Run the app with `npm run dev`
2. Open http://localhost:3000
3. Try doing X. You should see Y

## Next steps

Short congratulations sentence.

From here, extend the project:

- [Link to deeper docs](/docs/category/page)
- [Link to related guide](/guides/category/page)
- [Link to deployment](/guides/deployment/page)

Rules:

• frontmatter title must be $TECHNOLOGY | $CATEGORY
• do not add a packages field
• H1 must be action-oriented, not just a technology name
• Before you begin must be short bullet prerequisites with links where needed
• each H2 must be one step in sequence
• mark optional steps in the heading
• show code before explanation
• every code block must be complete and copyable
• include all imports in code blocks
• use title for file paths
• use npm2yarn on npm install, npx, and similar bash commands
• do not use the <Steps> component
• always include Test your $THING with numbered verification steps
• end with Next steps
• start Next steps with a short congratulations line
• group follow-up links by intent

Tutorial guide styleguide

Read STYLEGUIDE.md first.

Use this file for tutorials.

Goal:

• teach the reader how to build one specific thing with Mastra
• go deeper than a quickstart
• assume the reader already has a Mastra project
• teach concepts while building toward a complete result

Use this shape:

````mdx --- title: 'Guide: Building a $THING' description: Build a $THING that $WHAT_IT_DOES. ---

Building a $THING

In this guide, you'll build a $THING that $WHAT_IT_DOES. You'll learn how to $CONCEPT_1, $CONCEPT_2, and $CONCEPT_3.

Prerequisites

• Node.js v22.13.0 or later installed
• An API key from a supported Model Provider
• An existing Mastra project. Follow the installation guide if needed.

$STEP_1

Context on what this step does and why. Link to relevant reference docs.

```typescript title="src/mastra/index.ts" import { Mastra } from '@mastra/core'; // highlight-next-line import { NewThing } from '@mastra/core/new-thing';

// highlight-start const thing = new NewThing({ // configuration }); // highlight-end

export const mastra = new Mastra({ // highlight-next-line thing, });

Explain what changed. If the reader must create files or folders manually, say so after the code block.

## $STEP_2

Context for the next concept.

Use the right language tag for non-TypeScript files:

Content of the file

If a step creates multiple files, show each file in its own code block and add a brief explanation between them.

## $STEP_3

Context.

When updating a file shown earlier, show the full file again and highlight the changed lines:

import { Mastra } from '@mastra/core'; import { NewThing } from '@mastra/core/new-thing'; // highlight-next-line import { myAgent } from './agents/my-agent';

const thing = new NewThing({ // configuration });

export const mastra = new Mastra({ thing, // highlight-next-line agents: { myAgent }, });

## Test the $THING

Start the dev server and test what you built:

npm run dev

Explain where to go and how to test.

Provide a sample input:

Sample input to try

Describe the expected output. If responses are non-deterministic, say that output may vary, then show an example:

Expected output format

## Next steps

You can extend this $THING to:

- Extension idea 1
- Extension idea 2
- Extension idea 3

Learn more:

- [Link to related concept](/docs/category/page)
- [Link to external resource](https://example.com)

Rules:

• frontmatter title must be Guide: Building a $THING
• H1 must be Building a $THING
• start the intro with In this guide, you'll build...
• include what the reader will learn in the intro
• use Prerequisites, not Before you begin
• always require an existing Mastra project and link to the quickstart
• each H2 step should teach a concept, not just list an action
• headings should name what is being created
• when a file changes across steps, show the full file again
• mark changed lines with highlight-start, highlight-end, and highlight-next-line
• a step may create multiple files; show each file in its own code block with a title
• use the correct language tag for non-TypeScript files
• always include Test the $THING
• show how to start the dev server, where to navigate, a sample input, and expected output
• note when outputs may vary
• end with Next steps
• Next steps should include extension ideas and a Learn more list
• do not add a congratulations section
• do not use the <Steps> component
• use npm2yarn on install commands

Reference page styleguide

Read STYLEGUIDE.md first.

Use this file for reference/API pages.

Goal:

• document one class or function completely
• optimize for lookup, not concept teaching
• link to doc pages when a concept needs explanation

Use this shape:

````mdx --- title: 'Reference: $NAME | $CATEGORY' description: 'API reference for $NAME, $BRIEF_DESCRIPTION.' packages:

• '@mastra/core'
• '@mastra/<module>'

---

$NAME

Added in: @mastra/$PACKAGE@$VERSION

One or two sentences on what the class or function does and when to use it.

Link to alternatives when they exist.

Usage example

Brief sentence on the scenario.

```typescript title="src/mastra/index.ts" import { $Name } from '@mastra/<package>';

// Minimal working example

If the API has multiple calling patterns, show each one here with a brief explanation.

## Constructor parameters / Parameters

<PropertiesTable
  content={[
    {
      name: '$PARAM',
      type: '$TYPE',
      description: 'What this parameter does.',
      isOptional: true,
      defaultValue: '$DEFAULT',
    },
  ]}
/>

## Properties

<PropertiesTable
  content={[
    {
      name: '$PROPERTY',
      type: '$TYPE',
      description: 'What this property represents.',
    },
  ]}
/>

## Methods

### $METHOD_CATEGORY

#### `$methodName($PARAM, options?)`

One sentence on what the method does.

const result = await instance.$methodName('value', { option: true, });

## $DOMAIN_SPECIFIC_SECTION

Add sections for API-specific concerns such as tool configuration or agent tools. Use tables for capability lists and `<PropertiesTable>` for nested config.

## Additional configuration

Add advanced usage patterns that go beyond the basic parameters.

Rules:

• frontmatter title must be Reference: $NAME | $CATEGORY
• for functions, include parentheses in $NAME in frontmatter and H1
• for classes, use the class name in frontmatter and H1
• include **Added in:** only when the API was introduced in a specific release and the minimum version matters. Do not add it if the package is a net-new package
• place **Added in:** immediately after the H1
• omit **Added in:** for long-standing APIs
• link to alternative APIs right after the description when they exist
• put a minimal working usage example immediately after the description
• if the API has multiple calling patterns, show them in the Usage example section
• use <PropertiesTable> for constructor parameters, function parameters, and properties
• each <PropertiesTable> entry should include name, type, and description, and may include isOptional, properties, and defaultValue
• for nested types, use properties: [{ type: '$TYPE', parameters: [...] }]; do not put nested parameter objects directly inside properties
• check existing reference pages for <PropertiesTable> patterns and consistency
• group methods by category with H3 headings
• use H4 headings with backticked method signatures
• include parameter names in method headings
• every method must have at least one real code example
• add Returns: $Type after the code example when the return type is not obvious
• include an interface definition when the return type is a custom object
• add domain-specific H2 sections after the standard sections when needed
• use tables for capability lists
• link to doc pages instead of duplicating long conceptual explanations

Tips:

• For nested objects, put parameters inside a typed entry in properties:

  <PropertiesTable
    content={[
      {
        name: 'options',
        type: 'RunOptions',
        description: 'Options for the run.',
        properties: [
          {
            type: 'RunOptions',
            parameters: [
              {
                name: 'timeout',
                type: 'number',
                description: 'Timeout in milliseconds.',
                isOptional: true,
              },
            ],
          },
        ],
      },
    ]}
  />

Documentation styleguide

Use this file as the default writing guide for Mastra's documentation.

Core rules

• Write clearly and directly.
• Prefer short sentences, short paragraphs, simple words, and low jargon.
• Break up dense text with headings and bullet lists.
• Write docs for readers who may be tired, rushed, reading in a non-native language, or new to the ecosystem.
• You can check prose in Hemingway App.
• Also see Google's guides for inclusive documentation and accessible documentation.

Keep docs current

• Use current model names for providers such as OpenAI and Claude.
• Check packages/core/src/llm/model/provider-registry.json for the latest models supported by Mastra.

Scope

• Document how to use technologies with Mastra.
• Do not explain third-party technologies in depth unless the Mastra-specific integration requires it.
• Link to external docs when non-Mastra background is helpful.

Tone and wording

• Use a neutral, factual tone.
• Do not be funny, whimsical, or story-driven.
• Keep each page self-contained.
• Refer to the reader as you when needed.
• Refer to the product as Mastra, not we, us, our, or ours.
• Do not use I.
• Address the reader in the present tense.
• Use sentence case for titles.
• Use conjunctions where they make the sentence sound more natural.
• Use contractions for common phrases like don't, doesn't, can't, and isn't.
• Remove filler, weak adverbs, weasel words, clichés, and wordy phrases.
• Do not start sentences with So, There is, or There are.
• Use inclusive, gender-neutral, person-first wording.
• Write out abbreviations on first use, then add the abbreviation in parentheses.
• Avoid gerunds in titles when a clearer verb phrase works.
• Prefer active voice.
• Prefer imperative instructions.
• Do not write Let's... or Next, we will....
• Avoid weak instructions like You should... unless you are describing an expected result.
• Use You can... only for permission or optional choices.
• When order matters, lead with the location and end with the action.
• Do not wrap instructions in narrative or storytelling.
• When an instruction is opinionated, separate the required action from the opinionated choice used in the example.
• Use Ensure, not make sure.
• Use exclamation points rarely.

Links and references

• Link documented APIs on first mention on a page.
• Link them again under a new heading if needed.
• Do not repeat the same reference link over and over in one section.
• When a documented concept needs more detail than fits on the page, link to the relevant reference or doc page instead of duplicating content.

UI terms

• Bold UI labels, headings, section names, and product names that appear in the interface.
• Use select or open, not click.
• Do not include the word button unless it is required for clarity.
• Use open, not appears, for UI surfaces like modals.

Code explanations

• Put a short explanation before a code example.
• Use wording like The following example demonstrates... when helpful.
• After the code block, explain only what needs explanation.

Headings

• The page title is H1. New sections start at H2.
• Keep H2 and H3 headings short.
• Do not end headings with punctuation.
• Use code formatting in headings when the same text would be code in body text.
• If a page title contains a function name, wrap the function name in backticks.

Lists

• Use unordered lists when order does not matter.
• Use ordered lists for sequential steps.
• If list items become long or multi-paragraph, replace the list with headings.
• In list items, use a colon instead of an em dash to separate a label from its description.
• Capitalize the first word after a colon in a list item.
• End full-sentence list items with a period.
• Do not end fragment list items with a period.
• Alphabetize lists when there is no stronger ordering.

Examples

• Use for example for a single example in a sentence.
• Use e.g. in parentheses for a list of examples.
• Do not use e.g. for a complete list.

Accessibility

• Do not assume reader proficiency.
• Avoid words like just, easy, simple, hard, beginner, or senior when they judge difficulty or skill level.
• Use as little jargon as possible.
• Define jargon on first use or link to a trusted explanation.

Code formatting

• Use monospace formatting for code, commands, file names, and URLs.
• Format URLs as links when shown inline.
• Use the correct syntax highlighting for code blocks.
• Use shell syntax for terminal commands.
• Add npm2yarn metadata to npm install, npx, and npm run command blocks.

Quick checks

Before finishing a doc page, check that it:

• stays focused on Mastra
• uses direct, factual language
• avoids repeated reference links
• uses accessible UI wording
• uses correct code formatting and syntax tags
• uses headings and lists that are easy to scan