Integrating Mastra with Next.js: Two Approaches for AI-Powered Apps

One of the most common questions we've been receiving in our Discord and during our Live Workshops is: "How do I integrate Mastra with my Next.js application?" While we've supported Next.js for a while, we realized we needed to provide clearer guidance on the different integration approaches.

Today, we're excited to share our comprehensive guide on integrating Mastra with Next.js, offering two flexible approaches to fit different project needs.

Why Next.js + Mastra?

Next.js has become the go-to React framework for building modern web applications, offering an excellent developer experience with features like server components, API routes, and optimized builds. Combining Next.js with Mastra's agent capabilities creates a powerful foundation for AI-powered applications.

This integration lets you:

• Build AI agents directly into your web application
• Leverage Next.js server components and server actions for AI processing
• Create streaming AI responses with minimal client-side code
• Deploy everything together or as separate services based on your scaling needs

Two Integration Approaches

We've documented two main ways to integrate Mastra with your Next.js applications, each with its own advantages:

1. Separate Backend Integration

This approach is ideal for larger projects where you want to:

• Scale your AI backend independently from your frontend
• Maintain a clear separation of concerns
• Have more deployment flexibility
• Support multiple frontends with the same AI backend

// In your Next.js app
import { MastraClient } from "@mastra/client-js";

// Initialize the client
export const mastraClient = new MastraClient({
  baseUrl: process.env.NEXT_PUBLIC_MASTRA_API_URL || "http://localhost:4111",
});

// Use it in your components
const agent = mastraClient.getAgent("weatherAgent");
const response = await agent.generate(`What is the weather like in ${city}?`);

With this approach, your Mastra backend runs as a separate service, and your Next.js application communicates with it via the client library. This gives you the flexibility to scale each part independently and even support multiple frontends with the same AI backend.

Want to skip the backend setup? Request access to the Mastra Cloud Private Beta to instantly deploy your Mastra backend services without managing infrastructure.

2. Direct Integration

For smaller projects or prototypes, you can integrate Mastra directly into your Next.js application:

// In your Next.js server component or API route
import { mastra } from "@/mastra";

export async function getWeatherInfo(city: string) {
  const agent = mastra.getAgent("weatherAgent");
  const result = await agent.generate(`What is the weather like in ${city}?`);
  return result;
}

This approach bundles Mastra directly with your Next.js application, simplifying deployment and development. It's perfect for prototypes, MVPs, or smaller applications where you don't need to scale your AI backend separately.

Server Actions + Mastra: A Perfect Match

Next.js 14's server actions are particularly well-suited for AI agent integration. They allow you to run your AI agents on the server while providing a simple interface for client components:

// app/actions.ts
'use server'

import { mastra } from '@/mastra'

export async function getWeatherInfo(city: string) {
  const agent = mastra.getAgent('weatherAgent')
  const result = await agent.generate(`What is the weather like in ${city}?`)
  return result
}

// app/components/Weather.tsx
'use client'

import { getWeatherInfo } from '../actions'

export function Weather() {
  async function handleSubmit(formData: FormData) {
    const city = formData.get('city') as string
    const result = await getWeatherInfo(city)
    // Handle the result
  }

  return (
    <form action={handleSubmit}>
      <input name="city" placeholder="Enter city name" />
      <button type="submit">Get Weather</button>
    </form>
  )
}

This pattern keeps your API keys and agent logic secure on the server while providing a clean, type-safe interface for your client components.

Getting Started

To get started with Mastra and Next.js, you have two options:

1. For separate backend integration:

   • Create a new Mastra project with npx create-mastra@latest
   • Install the client in your Next.js app with npm install @mastra/client-js
   • Connect your Next.js app to your Mastra backend

2. For direct integration:

   • Navigate to your Next.js project root
   • Run npx mastra@latest init to set up Mastra in your project
   • Configure your next.config.js to include Mastra packages

For detailed step-by-step instructions, check out our comprehensive guide in the documentation.

Go Build Something Great!

Whether you're building a small prototype or a large-scale AI application, Mastra and Next.js provide a powerful combination for creating AI-powered web experiences.

We're excited to see what you build with Mastra and Next.js!