Installation

Create a new Avalon project and get up and running in minutes.

Requirements

Bun 1.0 or later (recommended)
Node.js 18+ (npm, pnpm, or yarn)

Create a new project

The fastest way to get started is with the create avalon scaffolder:

>_ Terminal

bun create avalon my-app

cd my-app

bun install

bun run dev

This creates a new directory my-app/ with a minimal project structure and starts the dev server at https://useavalon.dev.

Project structure

Scaffolded apps use modules (URL prefixes) under app/.

my-app/
├── app/
│   ├── modules/
│   │   ├── main/               # Site root (/)
│   │   │   ├── pages/          # File-system routes for this module
│   │   │   ├── components/     # UI, including islands
│   │   │   └── layouts/        # Module layout wrappers
│   │   └── about/              # /about — module name = URL prefix
│   └── shared/
│       ├── layouts/            # Root HTML shell
│       ├── components/
│       └── styles/             # Global CSS (via nitro globalCSS)
├── middleware/                 # Server middleware
├── routes/
│   └── api/                    # API routes (Nitro)
├── server/                     # SSR renderer entry
├── public/                     # Static assets
├── vite.config.ts              # Avalon + Nitro config
├── build.mjs                   # Production build entry
└── package.json

Manual installation

If you prefer to set up manually:

Install the core package

>_ Terminal

bun add @useavalon/avalon

bun add -d vite nitro

Create a Vite config

import { defineConfig } from 'vite';
import { avalon } from '@useavalon/avalon';

export default defineConfig(async () => {
  const plugins = await avalon({
    core: 'preact',
    modules: 'app/modules',
    layoutsDir: 'app/shared/layouts',
    integrations: ['preact'],
    nitro: {
      preset: 'node_server',
      streaming: true,
      clientEntry: 'app/entry-client',
      globalCSS: ['app/shared/styles/main.css'],
    },
  });
  return { plugins };
});