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:

vite.config.ts

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.

vite.config.ts

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:

aero.config.ts

import { defineConfig } from '@aero-js/core/config'

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

vite.config.ts

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:

aero.config.ts

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/*

<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

.env

API_SECRET=xxx
VITE_PUBLIC_API=https://api.example.com

<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 and Hypermedia to enable and use them. HTMX and Alpine.js work without these flags.