Skip to main content
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'
	import header from '@components/header'
	import site from '@content/site'
</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.

​
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

ToolRoleWhy it helps
ViteDev server and bundlerFast HMR, plugin system, asset bundling
NitroServer engine (optional)API routes, server deployment
HTMXServer-driven interactivityDynamic HTML updates without full page reloads
AlpineLightweight JS in markupDeclarative UI directly in HTML
External references: Vite, Nitro, HTMX, Alpine.js.

​
Packages

Aero is published as a set of focused packages:
PackageDescription
@aero-js/coreRuntime, Vite integration, and Aero orchestration
@aero-js/createScaffold new projects from the minimal or fullstack template
@aero-js/viteThe Aero Vite plugin
@aero-js/configdefineConfig and createViteConfig for typed aero.config.ts
@aero-js/contentContent collections — getCollection(), render(), schema validation
@aero-js/cliaero check and aero doctor for type-checking and diagnostics
Most projects only need @aero-js/core and @aero-js/vite (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.