|
| 1 | +--- |
| 2 | +title: "Bun Integration | Deployment" |
| 3 | +description: "Learn how to use Bun runtime features in your Mastra applications" |
| 4 | +--- |
| 5 | + |
| 6 | +# Bun Integration |
| 7 | + |
| 8 | +Mastra supports Bun as a runtime environment with optional native Bun components for bundling and serving. This guide covers how to leverage Bun-specific features in your Mastra applications. |
| 9 | + |
| 10 | +## Bun-Native Server |
| 11 | + |
| 12 | +When running on Bun, you can use the native `Bun.serve()` for better performance instead of `@hono/node-server`. |
| 13 | + |
| 14 | +### Automatic Detection |
| 15 | + |
| 16 | +Use `createServer()` which automatically detects the runtime: |
| 17 | + |
| 18 | +```typescript |
| 19 | +import { createServer } from "@mastra/deployer/server"; |
| 20 | +import { mastra } from "./mastra"; |
| 21 | + |
| 22 | +// Automatically uses Bun.serve() on Bun, @hono/node-server on Node.js |
| 23 | +const server = await createServer(mastra, { tools: {} }); |
| 24 | +``` |
| 25 | + |
| 26 | +### Explicit Bun Server |
| 27 | + |
| 28 | +For explicit Bun usage: |
| 29 | + |
| 30 | +```typescript |
| 31 | +import { createBunServer } from "@mastra/deployer/server"; |
| 32 | +import { mastra } from "./mastra"; |
| 33 | + |
| 34 | +// Throws an error if not running on Bun |
| 35 | +const server = await createBunServer(mastra, { tools: {} }); |
| 36 | +``` |
| 37 | + |
| 38 | +## Storage on Bun |
| 39 | + |
| 40 | +### LibSQLStore |
| 41 | + |
| 42 | +The `@mastra/libsql` storage adapter works on Bun without any additional configuration. LibSQL's client library has native Bun support: |
| 43 | + |
| 44 | +```typescript |
| 45 | +import { Mastra } from "@mastra/core"; |
| 46 | +import { LibSQLStore } from "@mastra/libsql"; |
| 47 | + |
| 48 | +export const mastra = new Mastra({ |
| 49 | + storage: new LibSQLStore({ |
| 50 | + id: "my-store", |
| 51 | + url: "file:./data.db", // Works on Bun |
| 52 | + }), |
| 53 | +}); |
| 54 | +``` |
| 55 | + |
| 56 | +For in-memory databases (useful for development): |
| 57 | + |
| 58 | +```typescript |
| 59 | +const storage = new LibSQLStore({ |
| 60 | + id: "memory-store", |
| 61 | + url: ":memory:", |
| 62 | +}); |
| 63 | +``` |
| 64 | + |
| 65 | +## Custom Bundler Engines |
| 66 | + |
| 67 | +Mastra uses Rollup as the default bundler for production builds. If you're running on Bun, you can configure the native Bun bundler for faster build times. |
| 68 | + |
| 69 | +## Using the Bun Bundler |
| 70 | + |
| 71 | +If you're running your Mastra application on Bun, you can use the native Bun bundler for faster build times. |
| 72 | + |
| 73 | +### Installation |
| 74 | + |
| 75 | +```bash |
| 76 | +bun add @mastra/bundler-bun@beta |
| 77 | +``` |
| 78 | + |
| 79 | +### Usage |
| 80 | + |
| 81 | +```typescript title="src/mastra/index.ts" |
| 82 | +import { Mastra } from "@mastra/core"; |
| 83 | +import { createBunEngine } from "@mastra/bundler-bun"; |
| 84 | + |
| 85 | +export const mastra = new Mastra({ |
| 86 | + bundler: { |
| 87 | + engine: createBunEngine(), |
| 88 | + }, |
| 89 | +}); |
| 90 | +``` |
| 91 | + |
| 92 | +### Configuration Options |
| 93 | + |
| 94 | +The Bun bundler engine accepts these options: |
| 95 | + |
| 96 | +| Option | Type | Default | Description | |
| 97 | +|--------|------|---------|-------------| |
| 98 | +| `minify` | `boolean` | `true` | Enable minification | |
| 99 | +| `sourcemap` | `"external" \| "inline" \| "none"` | `"none"` | Source map generation | |
| 100 | +| `target` | `"bun" \| "node" \| "browser"` | `"bun"` | Build target environment | |
| 101 | + |
| 102 | +Example with options: |
| 103 | + |
| 104 | +```typescript title="src/mastra/index.ts" |
| 105 | +import { Mastra } from "@mastra/core"; |
| 106 | +import { createBunEngine } from "@mastra/bundler-bun"; |
| 107 | + |
| 108 | +export const mastra = new Mastra({ |
| 109 | + bundler: { |
| 110 | + engine: createBunEngine({ |
| 111 | + minify: false, |
| 112 | + sourcemap: "external", |
| 113 | + target: "bun", |
| 114 | + }), |
| 115 | + }, |
| 116 | +}); |
| 117 | +``` |
| 118 | + |
| 119 | +## Using the Default Rollup Bundler |
| 120 | + |
| 121 | +The default Rollup bundler is used automatically when no custom engine is specified. You can also explicitly configure it: |
| 122 | + |
| 123 | +```typescript title="src/mastra/index.ts" |
| 124 | +import { Mastra } from "@mastra/core"; |
| 125 | +import { createRollupEngine } from "@mastra/deployer/engines"; |
| 126 | + |
| 127 | +export const mastra = new Mastra({ |
| 128 | + bundler: { |
| 129 | + engine: createRollupEngine(), |
| 130 | + }, |
| 131 | +}); |
| 132 | +``` |
| 133 | + |
| 134 | +## Creating a Custom Bundler Engine |
| 135 | + |
| 136 | +You can create custom bundler engines by implementing the `BundlerEngine` interface: |
| 137 | + |
| 138 | +```typescript |
| 139 | +import type { BundlerEngine, BundlerEngineOptions, BundlerEngineOutput } from "@mastra/core/bundler"; |
| 140 | + |
| 141 | +export class CustomBundlerEngine implements BundlerEngine { |
| 142 | + readonly name = "custom"; |
| 143 | + |
| 144 | + async bundle(options: BundlerEngineOptions): Promise<BundlerEngineOutput> { |
| 145 | + // options.entryPoint - The main entry file path |
| 146 | + // options.outputDir - Where to write the bundled output |
| 147 | + // options.outputFile - The output filename (e.g., "index.mjs") |
| 148 | + // options.externals - Packages to exclude from bundling |
| 149 | + // options.sourcemap - Whether to generate source maps |
| 150 | + |
| 151 | + // Implement your bundling logic here |
| 152 | + // ... |
| 153 | + |
| 154 | + return { |
| 155 | + success: true, |
| 156 | + outputPath: `${options.outputDir}/${options.outputFile}`, |
| 157 | + }; |
| 158 | + } |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +### BundlerEngineOptions |
| 163 | + |
| 164 | +| Property | Type | Description | |
| 165 | +|----------|------|-------------| |
| 166 | +| `entryPoint` | `string` | Absolute path to the entry file | |
| 167 | +| `outputDir` | `string` | Directory for the bundled output | |
| 168 | +| `outputFile` | `string` | Name of the output file | |
| 169 | +| `externals` | `string[]` | Packages to exclude from the bundle | |
| 170 | +| `sourcemap` | `boolean` | Whether to generate source maps | |
| 171 | + |
| 172 | +### BundlerEngineOutput |
| 173 | + |
| 174 | +| Property | Type | Description | |
| 175 | +|----------|------|-------------| |
| 176 | +| `success` | `boolean` | Whether the bundling succeeded | |
| 177 | +| `outputPath` | `string` | Path to the generated bundle | |
| 178 | +| `error` | `Error` (optional) | Error details if bundling failed | |
| 179 | + |
| 180 | +## Runtime Detection |
| 181 | + |
| 182 | +The Bun bundler engine requires the Bun runtime. It will throw an error if used outside of Bun: |
| 183 | + |
| 184 | +```typescript |
| 185 | +// This will throw if not running in Bun |
| 186 | +const engine = createBunEngine(); |
| 187 | +``` |
| 188 | + |
| 189 | +For projects that need to support multiple runtimes, you can conditionally use the bundler: |
| 190 | + |
| 191 | +```typescript title="src/mastra/index.ts" |
| 192 | +import { Mastra } from "@mastra/core"; |
| 193 | + |
| 194 | +const getBundlerConfig = async () => { |
| 195 | + if (typeof globalThis.Bun !== "undefined") { |
| 196 | + const { createBunEngine } = await import("@mastra/bundler-bun"); |
| 197 | + return { engine: createBunEngine() }; |
| 198 | + } |
| 199 | + return {}; // Use default Rollup bundler |
| 200 | +}; |
| 201 | + |
| 202 | +export const mastra = new Mastra({ |
| 203 | + bundler: await getBundlerConfig(), |
| 204 | +}); |
| 205 | +``` |
0 commit comments