A template for AHA-Stack projects: Astro + HTMX + Alpine.js + Tailwind CSS v4
This template serves as a proof of concept for reusable AHA-Stack applications with server-side fragment rendering.
- Astro 5 - Static & Server-Side Rendering
- HTMX - Server-side interactivity via HTML fragments
- Alpine.js - Lightweight client interactivity
- Tailwind CSS v4 - Utility-first CSS
- Cloudflare Workers - Edge deployment
| Package | Description |
|---|---|
| @casoon/fragment-renderer | Renders Astro components as HTML fragments for HTMX responses |
| @casoon/skibidoo-ui | SSR-first UI components for the AHA-Stack |
The AHA-Stack combines the benefits of server-side rendering with targeted client interactivity:
┌─────────────────────────────────────────────────────────────┐
│ Browser │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ HTMX Request (e.g. sorting, pagination) │ │
│ │ GET /api/users?page=2&sortField=name │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Server (Astro API Route) │ │
│ │ 1. Load data from DB │ │
│ │ 2. Filter, sort, paginate │ │
│ │ 3. Render fragment with @casoon/fragment-renderer │ │
│ │ 4. Return HTML + styles │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ HTMX replaces DOM element with new HTML │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Benefits:
- No client-side state management
- Data logic stays on the server
- Components deliver their own styles
- Progressive - works without JavaScript
# Clone repository
git clone https://github.com/casoon/aha-template.git
cd aha-template
# Install dependencies
pnpm install
# Start development server
pnpm devsrc/
├── layouts/
│ └── BaseLayout.astro # Base layout with HTMX/Alpine setup
├── pages/
│ ├── api/
│ │ └── users.ts # API endpoint with fragment rendering
│ ├── index.astro
│ └── examples.astro
├── i18n/
│ └── translations.ts # i18n (de/en)
└── styles/
└── base.css # Tailwind + custom styles
The core concept: Astro components from @casoon/skibidoo-ui are rendered server-side via the registry and returned as HTML fragments to HTMX.
// src/pages/api/users.ts
import { createAstroRuntime } from "@casoon/fragment-renderer";
import { createPartialRegistry } from "@casoon/skibidoo-ui/registry";
// Create runtime with UI registry
const runtime = createAstroRuntime({
components: createPartialRegistry(["ui-grid"]),
});
export const GET: APIRoute = async ({ url }) => {
const page = parseInt(url.searchParams.get("page") || "1");
const sortField = url.searchParams.get("sortField");
// Load and process data (server-side!)
const data = await fetchAndProcessData({ page, sortField });
// Render component as HTML fragment
const html = await runtime.renderToString({
componentId: "ui-grid",
props: {
data,
currentPage: page,
sortField,
endpoint: "/api/users",
},
});
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
};Add @casoon/skibidoo-ui to your Vite SSR config:
// astro.config.mjs
export default defineConfig({
vite: {
ssr: {
noExternal: ["@casoon/skibidoo-ui"],
},
},
});| Component ID | Description |
|---|---|
ui-grid |
Data grid with sort/filter/pagination |
ui-form |
Dynamic form with validation |
ui-button |
Button with variants |
ui-card |
Card container |
ui-alert |
Alert/notification box |
ui-modal |
Modal dialog |
ui-input |
Text input field |
ui-select |
Select dropdown |
ui-datepicker |
Date picker |
pnpm dev # Development server
pnpm build # Production build
pnpm preview # Build preview
pnpm cf-deploy # Deploy to Cloudflare Workers
pnpm lint # Biome linting
pnpm format # Biome formatting# Configure wrangler.toml, then:
pnpm cf-deploy- Node.js >= 22
- pnpm
- Integrate more skibidoo-ui components
- Form handling with server-side validation
- Auth example
- Database integration (D1/Drizzle)
MIT