> ## 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.

# 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:**

```html pages/index.html theme={"theme":"github-dark-default"}
<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

<CardGroup cols={2}>
  <Card title="File-based routing" icon="route">
    `client/pages/about.html` becomes `/about`. Dynamic routes use `[param].html` and `getStaticPaths()`.
  </Card>

  <Card title="Components & layouts" icon="puzzle">
    Import `.html` templates and use them as `<name-component>` or `<name-layout>` in your markup.
  </Card>

  <Card title="Loops & conditionals" icon="repeat">
    Use `for`, `if`, `else-if`, `else`, and `switch` directives with `{ }` expressions directly in markup.
  </Card>

  <Card title="Content collections" icon="database">
    Put data in `content/`. Use `getCollection()` and `render()` for Markdown-driven pages.
  </Card>

  <Card title="Slots" icon="between-horizontal-start">
    Layouts expose `<slot>` for page content. Named slots and slot passthrough let you thread content through nested layouts.
  </Card>

  <Card title="HMR everywhere" icon="zap">
    CSS, HTML, content, and client scripts all hot-reload in dev. Powered by Vite.
  </Card>

  <Card title="Optional reactivity" icon="sparkles">
    Opt into `<script is:state>`, bindings, and reactive props — no Virtual DOM, no mandatory runtime.
  </Card>

  <Card title="Hypermedia actions" icon="radio">
    `GET` / `POST` fragment swaps with lifecycle events when you enable `hypermedia: true`.
  </Card>
</CardGroup>

## 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](https://nitro.build/) — 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](https://vitejs.dev/), [Nitro](https://nitro.build/), [HTMX](https://htmx.org/), [Alpine.js](https://alpinejs.dev/).

## 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       |

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

## Next steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/getting-started/installation">
    Scaffold your first project and have a site running in minutes.
  </Card>

  <Card title="Project structure" icon="folder-open" href="/getting-started/structure">
    Learn how pages, layouts, components, and content are organized.
  </Card>

  <Card title="Reactivity" icon="sparkles" href="/getting-started/reactivity">
    Client state and bindings with `<script is:state>`.
  </Card>

  <Card title="Hypermedia" icon="radio" href="/getting-started/hypermedia">
    Server fragment swaps with `GET` / `POST` actions.
  </Card>
</CardGroup>