Skip to main content
Prerequisites:
  • A Netlify account
  • Node.js version 22 or higher
  • A Mastra project ready to deploy
The Netlify deployer enables deployment of Mastra applications to Netlify Functions, providing serverless hosting with automatic configuration using Netlify’s Frameworks API.

​
Installation

1

Install the Netlify deployer

Install the @mastra/deployer-netlify package:
pnpm add @mastra/deployer-netlify
2

Configure the deployer

Add the Netlify deployer to your Mastra configuration:
import { Mastra } from '@mastra/core/mastra';
import { NetlifyDeployer } from '@mastra/deployer-netlify';

const deployer = new NetlifyDeployer();

const mastra = new Mastra({
  deployer,
  // ... other Mastra configuration
});
The Netlify deployer requires no configuration options. It automatically sets up everything needed for Netlify Functions.
3

Build your project

Run your build command. The deployer will:
  • Bundle your application for Netlify Functions
  • Install dependencies with Linux x64 architecture
  • Generate Netlify Frameworks API configuration
  • Set up routing to the API function
pnpm build
This generates:
  • .netlify/v1/functions/api/ - Your bundled function and dependencies
  • .netlify/v1/config.json - Netlify Frameworks API configuration
4

Deploy to Netlify

Deploy using the Netlify CLI:
npx netlify deploy --prod
Or connect your Git repository to Netlify for automatic deployments.

​
How it works

The Netlify deployer:
  1. Bundles your application using Rollup with ESM shim enabled
  2. Creates an entry point using Hono’s Netlify adapter:
import { handle } from 'hono/netlify'
import { mastra } from '#mastra';
import { createHonoServer, getToolExports } from '#server';
import { tools } from '#tools';

const app = await createHonoServer(mastra, { 
  tools: getToolExports(tools) 
});

export default handle(app)
  1. Installs dependencies with specific architecture targeting:
    • OS: linux
    • CPU: x64
    • libc: gnu
  2. Generates Frameworks API config (.netlify/v1/config.json): 
{
  "functions": {
    "directory": ".netlify/v1/functions",
    "node_bundler": "none",
    "included_files": [".netlify/v1/functions/**"]
  },
  "redirects": [
    {
      "force": true,
      "from": "/*",
      "to": "/.netlify/functions/api/:splat",
      "status": 200
    }
  ]
}
This configuration:
  • Points Netlify to the functions directory
  • Disables Netlify’s bundling (Mastra pre-bundles)
  • Routes all requests to your API function

​
Storage compatibility

The Netlify deployer does not support @mastra/libsql because it uses native Node.js bindings with file URLs that cannot run in serverless environments.
Use these storage options instead:
  • @mastra/pg - PostgreSQL (recommended)
  • @mastra/mongodb - MongoDB
  • @mastra/dynamodb - AWS DynamoDB
The deployer automatically checks for incompatible dependencies during the build process.

​
Environment variables

Environment variables can be configured in multiple ways:
  1. Local .env files - Automatically loaded during development
  2. Netlify Dashboard - Set in Site Settings → Environment Variables
  3. Netlify CLI - Use netlify env commands
# Set environment variable via CLI
netlify env:set DATABASE_URL "postgresql://..."
  1. netlify.toml - For build-time variables:
[build.environment]
  NODE_VERSION = "22"

​
Project structure

After building, your project will have this structure: 
your-project/
├── .netlify/
│   └── v1/
│       ├── config.json          # Frameworks API configuration
│       └── functions/
│           └── api/
│               ├── index.mjs    # Bundled application
│               ├── package.json # Dependencies
│               └── node_modules/
├── src/
│   └── mastra/
│       └── index.ts             # Your Mastra config
├── netlify.toml                 # Optional Netlify config
└── package.json

​
Custom Netlify configuration

You can add a netlify.toml file for additional configuration: 
[build]
  command = "pnpm build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "22"

[functions]
  node_bundler = "none"
  directory = ".netlify/v1/functions"
The deployer’s automatic configuration takes precedence for function bundling and routing, but you can use netlify.toml for other settings like build commands and environment variables.

​
Deployment options

​
Using Netlify CLI

# Deploy to preview
netlify deploy

# Deploy to production
netlify deploy --prod

# Deploy with build
netlify deploy --prod --build

​
Using Git integration

  1. Push your code to GitHub, GitLab, or Bitbucket
  2. Connect your repository in the Netlify dashboard
  3. Configure build settings:
    • Build command: pnpm build
    • Publish directory: Leave empty (functions are auto-detected)
  4. Deploy automatically on push

​
Using Netlify Drop

For manual deployments:
  1. Build your project locally: pnpm build
  2. Drag and drop the .netlify folder to Netlify Drop

​
Troubleshooting

The deployer bundles your code and installs dependencies separately. Make sure:
  • All dependencies are in package.json
  • You’re using the correct import paths
  • ESM syntax is used consistently
Verify that:
  • The .netlify/v1/config.json file was generated
  • Your build completed successfully
  • The function is in .netlify/v1/functions/api/
The deployer automatically detects @mastra/libsql and throws an error because native bindings don’t work in Netlify Functions. Switch to @mastra/pg or another compatible storage option.
The deployer automatically installs dependencies for Linux x64. If you see errors related to native modules:
  • Clear node_modules and rebuild
  • Check that the package supports Linux x64
  • Consider using a different package
Netlify Functions have a default timeout of 10 seconds (26 seconds for Pro plans). For longer operations:
  • Upgrade to a Pro plan
  • Use background functions for async tasks
  • Optimize your code for faster execution

​
Performance tips

  1. Enable caching - Use Netlify’s cache headers for static responses
  2. Minimize dependencies - Keep your bundle size small
  3. Use background functions - For long-running tasks
  4. Configure regions - Deploy closer to your users (available on Pro plans)

​
Next steps

Server & API

Learn about Mastra’s server capabilities

Storage options

Explore compatible storage backends

Observability

Set up logging and tracing

Netlify Docs

Official Netlify Functions documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us