> ## Documentation Index
> Fetch the complete documentation index at: https://aerojs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure Aero through the Vite plugin or a dedicated aero.config.ts file.

Aero is configured through the `aero()` Vite plugin. For larger projects, you can move Aero options into a dedicated `aero.config.ts`.

## The Vite plugin

Add `aero()` to `vite.config.ts`:

```ts vite.config.ts theme={"theme":"github-dark-default"}
import { defineConfig } from 'vite'
import { aero } from '@aero-js/core/vite'

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

### Plugin options

| Option       | Type                           | Description                                                            |
| ------------ | ------------------------------ | ---------------------------------------------------------------------- |
| `content`    | `boolean \| object`            | Enable content collections. Default `false`.                           |
| `server`     | `boolean`                      | Enable Nitro for API routes. Default `false`.                          |
| `site`       | `string \| object`             | Canonical site URL. Exposed as `import.meta.env.SITE` and `Aero.site`. |
| `redirects`  | `Array<{ from, to, status? }>` | Path redirects for dev and production.                                 |
| `middleware` | `Array`                        | Dev-only request handlers.                                             |
| `dirs`       | `object`                       | Override `client`, `server`, and `dist` directory names.               |
| `apiPrefix`  | `string`                       | URL prefix for API routes. Default `'/api'`.                           |
| `reactivity` | `boolean`                      | Enable `<script is:state>` and reactive bindings. Default `false`.     |
| `hypermedia` | `boolean`                      | Enable `GET`/`POST`/… actions and fragment swaps. Default `false`.     |

```ts vite.config.ts theme={"theme":"github-dark-default"}
import { defineConfig } from 'vite'
import { aero } from '@aero-js/core/vite'

export default defineConfig({
	plugins: [
		aero({
			site: 'https://example.com',
			content: true,
			server: true,
		}),
	],
})
```

## Dedicated aero.config.ts

For projects with more complex configuration, use `@aero-js/core/config` to keep Aero options separate from Vite:

```ts aero.config.ts theme={"theme":"github-dark-default"}
import { defineConfig } from '@aero-js/core/config'

export default defineConfig({
	site: { url: 'https://example.com' },
	content: true,
	server: true,
})
```

```ts vite.config.ts theme={"theme":"github-dark-default"}
import { createViteConfig } from '@aero-js/core/vite-config'

export default createViteConfig()
```

`createViteConfig()` with no arguments auto-loads `aero.config.ts` from the project root.

### Env-aware config

Pass a function to `defineConfig()` to vary options by mode:

```ts aero.config.ts theme={"theme":"github-dark-default"}
import { defineConfig } from '@aero-js/core/config'

export default defineConfig(env => ({
	site: env.mode === 'production' ? 'https://example.com' : 'http://localhost:5173',
	content: true,
	server: true,
}))
```

## Path aliases

Aero injects default path aliases so imports work without `tsconfig.json` configuration:

| Alias           | Resolves to               |
| --------------- | ------------------------- |
| `@components/*` | `client/components/*`     |
| `@layouts/*`    | `client/layouts/*`        |
| `@pages/*`      | `client/pages/*`          |
| `@content/*`    | `content/*`               |
| `@styles/*`     | `client/assets/styles/*`  |
| `@scripts/*`    | `client/assets/scripts/*` |
| `@images/*`     | `client/assets/images/*`  |

```html theme={"theme":"github-dark-default"}
<script is:build>
	import base from '@layouts/base.html'
	import header from '@components/header.html'
</script>

<link rel="stylesheet" href="@styles/global.css" />
```

Add custom aliases in `tsconfig.json` under `compilerOptions.paths`. They merge with the defaults.

## Environment variables

Aero uses Vite's environment variable system. Variables in `.env` files are available in build scripts by default. Prefix with `VITE_` to expose them to client scripts:

| Prefix  | Available in                     |
| ------- | -------------------------------- |
| (none)  | Build scripts and server only    |
| `VITE_` | Build scripts and client scripts |

```bash .env theme={"theme":"github-dark-default"}
API_SECRET=xxx
VITE_PUBLIC_API=https://api.example.com
```

```html theme={"theme":"github-dark-default"}
<script is:build>
	const secret = import.meta.env.API_SECRET
	const publicApi = import.meta.env.VITE_PUBLIC_API
</script>
```

Vite loads `.env`, `.env.local`, `.env.[mode]`, and `.env.[mode].local` in order. Shell variables override file values.

## Reactivity and hypermedia

Optional client features behind feature flags (both default `false`):

| Flag         | Enables                                                                    |
| ------------ | -------------------------------------------------------------------------- |
| `reactivity` | `<script is:state>`, structural updates, reactive props, reactive bindings |
| `hypermedia` | `GET` / `POST` / … actions, fragment swaps, lifecycle events               |

`busy` and post-swap binding processing require **both** flags.

See [Reactivity](/getting-started/reactivity) and [Hypermedia](/getting-started/hypermedia) to enable and use them. HTMX and Alpine.js work without these flags.