Introduction

Build fast, HTML-first static sites and full-stack apps with a native web feel.

Aero is a static site generator (and optional full-stack framework) built around plain HTML. You write .html files with optional <script> and <style> blocks, Aero compiles them at build time, and you get a dist/ folder you can deploy anywhere. When you need more — API routes, server-side logic, deployment adapters — you opt into Nitro. Nothing is forced on you.

It looks like this:

pages/index.html

<script is:build>
	import base from '@layouts/base.html'
	import header from '@components/header.html'
	import site from '@content/site.ts'
</script>

<base-layout>
	<header-component title="{ site.title }" subtitle="{ site.subtitle }" />
	<p>{ site.description }</p>
</base-layout>

<script>
	import someFunction from '@scripts/someModule'
	someFunction()
</script>

Key features

File-based routing

client/pages/about.html becomes /about. Dynamic routes use [param].html and getStaticPaths().

Components & layouts

Import .html templates and use them as <name-component> or <name-layout> in your markup.

Loops & conditionals

Use for, if, else-if, else, and switch directives with { } expressions directly in markup.

Content collections

Put data in content/. Use getCollection() and render() for Markdown-driven pages.

Slots

Layouts expose <slot> for page content. Named slots and slot passthrough let you thread content through nested layouts.

HMR everywhere

CSS, HTML, content, and client scripts all hot-reload in dev. Powered by Vite.

Optional reactivity

Opt into <script is:state>, bindings, and reactive props — no Virtual DOM, no mandatory runtime.

Hypermedia actions

GET / POST fragment swaps with lifecycle events when you enable hypermedia: true.

Who it’s for

Aero is a good fit if you:

• Want to write HTML, CSS, and JavaScript without a framework abstraction in the way
• Need a fast static site with no runtime or hydration overhead
• Want to use HTMX or Alpine.js for interactivity without fighting a compiler
• Occasionally need API routes but don’t want to commit to a full server framework

Core ideas

HTML-first authoring. Pages, layouts, and components are .html files. The only additions are { } expressions for interpolation and a handful of directives (if, for, slot). The source looks like HTML; the output is HTML.

Static by default. pnpm build produces a plain dist/ folder. No framework runtime ships to the browser. Deploy to any static host, or open via file://.

Optional full-stack with Nitro. Set server: true in your config to enable Nitro — file-based API routes under server/api/, universal deployment presets, and a preview:api command. You get API routes from the same project without changing how you write pages.

Zero runtime. Build-time code lives in <script is:build> and is completely stripped from output. Client scripts are plain <script> tags, bundled by Vite. No hydration orchestrator, no Virtual DOM.

Core stack

Tool	Role	Why it helps
Vite	Dev server and bundler	Fast HMR, plugin system, asset bundling
Nitro	Server engine (optional)	API routes, server deployment
HTMX	Server-driven interactivity	Dynamic HTML updates without full page reloads
Alpine	Lightweight JS in markup	Declarative UI directly in HTML

External references: Vite, Nitro, HTMX, Alpine.js.

Packages

Aero is published as a set of focused packages:

Package	Description
@aero-js/core	Runtime, Vite plugin, config helpers, and compile-check (see subpaths below)
@aero-js/create	Scaffold new projects from bundled minimal or fullstack templates
@aero-js/content	Content collections — getCollection(), render(), schema validation
@aero-js/cli	aero check and aero doctor for type-checking and diagnostics
@aero-js/reactivity	Signal store, bindings, and process API (used via core when enabled)
@aero-js/hypermedia	Action functions, swap engine, and lifecycle events
@aero-js/diagnostics	Shared diagnostic types and formatters for CLI, core, and the VS Code extension

@aero-js/core subpath exports

Subpath	Description
@aero-js/core/vite	The Aero Vite plugin
@aero-js/core/config	defineConfig, loadAeroConfig, and config types
@aero-js/core/vite-config	createViteConfig and getDefaultOptions for Vite
@aero-js/core/compile-check	Node-only template compile checks for tooling

Most projects only need @aero-js/core (import subpaths as needed) or @aero-js/create to scaffold. The other packages are opt-in.

Next steps

Installation

Scaffold your first project and have a site running in minutes.

Project structure

Learn how pages, layouts, components, and content are organized.

Reactivity

Client state and bindings with <script is:state>.

Hypermedia

Server fragment swaps with GET / POST actions.