# Build Configuration

Customize the build process with Vite plugins and build-time constants

Customize how your project is built using `vite.config.ts` in your project root. Add Vite plugins for frontend builds or define build-time constants.

## Basic Configuration

```typescript
import { defineConfig } from 'vite';

export default defineConfig({
  // Configuration options here
});
```

## Configuration Options

### plugins

Add Vite plugins for frontend builds (`src/web/`). Plugins run after built-in plugins (React, environment variables).

```typescript
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});
```

See the [Vite plugin documentation](https://vitejs.dev/plugins/) for available plugins.

> [!NOTE]
> **Frontend Only**
> Vite plugins apply to frontend builds only. Server code is bundled separately with Bun.

### define

Replace identifiers with constant values at build time. Values must be JSON-stringified.

```typescript
import { defineConfig } from 'vite';

export default defineConfig({
  define: {
    'API_VERSION': JSON.stringify('v2'),
    '__DEV__': JSON.stringify(false),
  },
});
```

> [!WARNING]
> **Reserved Keys**
> These keys are set by the build system and will override any user-defined values:
> - `import.meta.env.AGENTUITY_PUBLIC_*` (Agentuity internal variables)
> - `process.env.NODE_ENV`

## Environment Variables

Environment variables with these prefixes are available in frontend code:

| Prefix | Description |
|--------|-------------|
| `VITE_*` | Standard Vite convention |
| `AGENTUITY_PUBLIC_*` | Agentuity convention |
| `PUBLIC_*` | Short form |

```typescript
// .env.local
AGENTUITY_PUBLIC_API_URL=https://api.example.com

// src/web/App.tsx
const apiUrl = import.meta.env.AGENTUITY_PUBLIC_API_URL;
```

> [!WARNING]
> **Security**
> Public environment variables are bundled into frontend code and visible in the browser. Never put secrets or API keys in public variables.

## Build Architecture

Agentuity uses a hybrid build system:

| Component | Tool | Output |
|-----------|------|--------|
| Frontend (`src/web/`) | Vite | `.agentuity/client/` |
| Server (agents, routes) | Bun | `.agentuity/app.js` |

This separation allows Vite's optimizations for frontend (HMR, tree-shaking, CSS processing) while using Bun's fast bundling for server code.

For details on how these components interact during development, see [Dev Server Architecture](/reference/cli/development#dev-server-architecture).

## Full Example

```typescript title="vite.config.ts"
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  // Vite plugins for frontend
  plugins: [tailwindcss()],

  // Build-time constants
  define: {
    'APP_VERSION': JSON.stringify('1.0.0'),
  },
});
```

## Next Steps

- [Tailwind CSS Setup](/cookbook/patterns/tailwind-setup): Add Tailwind styling to your frontend
- [Development Server](/reference/cli/development): Run the dev server with your configuration
- [Deployment](/reference/cli/deployment): Deploy with build configuration