Server

Add API routes, server-side logic, and full-stack capabilities with Nitro.

Aero is static-first: pnpm build produces a plain dist/ you can deploy anywhere. When you need API routes, server-side logic, or deployment adapters, opt in to Nitro with a single config flag. Nitro wraps your built HTML — it does not replace Aero’s page compiler.

Enable Nitro only when you need it. Static sites have no server to manage or pay for.

Enable Nitro

Set server: true in your config:

aero.config.ts

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

export default defineConfig({
	server: true,
})

Then add a nitro.config.ts at the project root:

nitro.config.ts

import { defineNitroConfig } from 'nitro/config'

export default defineNitroConfig({
	runtimeConfig: {
		appName: 'My Aero App',
	},
})

File conventions

Place server files under server/:

server/
├── api/           → API handlers at /api/*
├── routes/        → Additional route handlers
├── middleware/     → Nitro request-time middleware
├── plugins/       → Nitro lifecycle hooks
└── tasks/         → Runnable server tasks

API handlers

Files in server/api/ are served at /api/.... The filename determines the route and HTTP method:

server/api/submit.post.ts

import { defineHandler, readBody } from 'nitro/h3'

export default defineHandler(async event => {
	const body = await readBody(event)
	return { ok: true, message: body.message }
})

Use route parameters with [param] in the filename:

server/api/users/[id].ts

import { defineHandler, getRouterParam } from 'nitro/h3'

export default defineHandler(event => {
	const id = getRouterParam(event, 'id')
	return { id, name: `User ${id}` }
})

Preview after build

Use vp preview to serve the production build locally after vp build when Nitro is off or you used a static-only build (server: false, or vp build --mode static). That serves dist/ through Vite+ — no API routes.

When server: true, vp build also writes .output/. Preview the full app (static + API from one origin) after build:

Command	When to use
vpx nitro preview	Usual local check. Nitro reads build metadata from the project root, serves public assets from .output together with the server handler, and loads preview env files (.env.preview, .env.production, .env). Matches the command Nitro prints after build.
node .output/server/index.mjs	Production Node entry. Runs the bundled server exactly as on a Node deployment. Use for deploy-parity debugging, automation, or when you need the same startup as production without Nitro’s preview wrapper.

Run both from the project root (where nitro.config.ts lives). The fullstack starter lists nitro as a devDependency so vpx nitro preview uses your pinned local version.

HTMX and Alpine.js

Aero works naturally with HTMX and Alpine.js for adding interactivity. Because Aero outputs plain HTML with no framework runtime, these libraries integrate without conflicts. Include them via <script> tags — no special configuration needed.

When to use server vs static

Need	Approach
Marketing site, blog, docs	Static only (server: false)
Form submissions, auth, API calls	Enable Nitro (server: true)
Database access, server caching	Enable Nitro + configure storage/DB
HTMX partial responses	Enable Nitro + server routes