Getting Started with Avalon

Installation

Create a new Avalon project using the CLI:

bun create avalon my-app
cd my-app
bun install
bun run dev

Project Structure

Avalon uses a file-based routing system. Pages go in src/pages/ and interactive components go in src/islands/.

my-app/
├── src/
│   ├── pages/
│   │   └── index.tsx       # → /
│   ├── islands/
│   │   └── Counter.tsx     # interactive component
│   └── layouts/
│       └── _layout.tsx     # root layout
├── public/
├── vite.config.ts
└── package.json

Creating Your First Island

Islands are interactive components that hydrate on the client. Create one in src/islands/:

// src/islands/Counter.tsx
/** @jsxImportSource preact */
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 use it in a page with the island prop to control hydration:

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

export default async function Page() {
  return (
    <div>
      <h1>My Page</h1>
      <Counter island={{ condition: 'on:visible' }} />
    </div>
  );
}

Running the Dev Server

Start the development server with hot module replacement:

bun run dev

Open http://localhost:8012 to see your site.