Quick Start

Scaffold a new project

The fastest way to get started is with the Avalon CLI:

This will walk you through selecting your frameworks, styling approach, and deployment target.

Install dependencies

Start the dev server

Open https://useavalon.dev in your browser. You should see the Avalon welcome page.

Create a page

Scaffolded apps use module-based routing: each folder under app/modules/ owns its own pages/ tree. The main module maps to the site root, so add app/modules/main/pages/hello.tsx:

export default function HelloPage() {
  return (
    <div>
      <h1>Hello, Avalon</h1>
      <p>This page ships zero JavaScript.</p>
    </div>
  );
}

Visit https://useavalon.dev/hello — you'll see your page rendered as pure HTML with no client-side JavaScript.

Need a URL prefix (e.g. /about)? Add another module: app/modules/about/pages/index.tsx. See File-System Routing.

Add an island

Islands are interactive components that hydrate on the client. Create app/modules/main/components/Counter.tsx:

import { useState } from 'preact/hooks';

export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

Then import the island file directly (no barrel re-exports) and use the island prop to control when it hydrates:

import Counter from '../components/Counter.tsx';

export default function HelloPage() {
  return (
    <div>
      <h1>Hello, Avalon</h1>
      {/* Hydrates only when the user first interacts with it */}
      <Counter island={{ condition: 'on:interaction' }} />
    </div>
  );
}

Build for production

Avalon builds a Nitro server bundle in .output/. Deploy it to Node, Bun, Cloudflare Workers, Vercel, or any Nitro-compatible target.