ContextQMD
Back to Mastra

Deploy Mastra to Netlify | Deployment

docs/src/content/en/guides/deployment/netlify.mdx

2025-12-183.1 KB
Original Source

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

Deploy Mastra to Netlify

Use @mastra/deployer-netlify to deploy your Mastra server as serverless functions on Netlify. The deployer bundles your code and generates a .netlify directory conforming to Netlify's frameworks API, ready to deploy.

:::info This guide covers deploying the Mastra server. If you're using a server adapter or web framework, deploy the way you normally would for that framework. :::

Before you begin

You'll need a Mastra application and a Netlify account.

:::warning Netlify Functions use an ephemeral filesystem, so any storage you configure (including observability storage) must be hosted externally. If you're using LibSQLStore with a file URL, switch to a remotely hosted database. :::

Installation

Add the @mastra/deployer-netlify package to your project:

bash
npm install @mastra/deployer-netlify@latest

Import NetlifyDeployer and set it as the deployer in your Mastra configuration:

typescript
import { Mastra } from '@mastra/core'
// highlight-next-line
import { NetlifyDeployer } from '@mastra/deployer-netlify'

export const mastra = new Mastra({
  // highlight-next-line
  deployer: new NetlifyDeployer(),
})

Create a netlify.toml file with the following contents in your project root:

toml
[build]
  command = "mastra build"

Deploy

After setting up your project, push it to your remote Git provider of choice (e.g. GitHub).

<Steps> <StepItem> Connect your repository to Netlify. During the setup process, Netlify will detect your `netlify.toml` file and set the build command to `mastra build`. 
:::note

Remember to set your environment variables needed to run your application (e.g. your [model provider](/models/providers) API key).

:::
</StepItem> <StepItem> Once you're ready, click the **Deploy** button and wait for the first deployment to complete. It'll tell you that one function has been deployed. </StepItem> <StepItem> Verify your deployment at `https://<random-slug>.netlify.app/api/agents`, which should return a JSON list of your agents. 
Since the [Mastra server](/docs/server/mastra-server) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.

:::info

Netlify functions are typically deployed at `https://<random-slug>.netlify.app/.netlify/functions/api`. The `NetlifyDeployer` redirects any request from `/*` to `/.netlify/functions/api/:splat`, so you don't need to include the `.netlify/functions` prefix in your URLs.

:::
</StepItem> <StepItem> You can now call your Mastra endpoints over HTTP. 
:::warning
Set up [authentication](/docs/server/auth) before exposing your endpoints publicly.
:::
</StepItem> </Steps>