Starter Kit

Opinionated AI-first Astro starter with HTMX, Alpine.js, Tailwind CSS, DaisyUI, Supabase, and Resend.

It includes a public site, email/password auth, password reset and change flows, an authenticated /app area, versioned database migrations, and documentation plus agent skills for working in the repo.

Server-first HTML by default; minimal client JavaScript.

Stack

Layer	Tool	Role
App framework	Astro 7 (server mode, Vercel adapter)	Routes, layouts, SSR, endpoints
Server-driven UI	HTMX	Partial page updates
Local UI state	Alpine.js	Toggles, drawers, small client state
Styling	Tailwind CSS 4 + DaisyUI 5	Layout and components (lofi theme)
Backend	Supabase	Auth, Postgres, RLS
Email	Resend	Transactional email (server-only)

Features

Public site

• Home (/), About (/about), Contact (/contact) — placeholders to replace
• Public chrome: About / Contact / Log in on desktop; mobile drawer (PublicSidebar)
• 404 with the same public chrome
• Dynamic robots.txt and sitemap.xml from site config
• Canonical URLs, Open Graph tags, and web manifest from src/config/site.ts

Authentication

• Sign in (/auth/signin) — email + password via Supabase
• Request access (/auth/signup) — emails the requester and admin; does not create accounts
• Reset password (/auth/reset-password) — email link → callback → change password
• Change password (/app/account/change-password) — fresh recovery/login sessions change directly; older sessions must confirm the current password
• Sign out from the app sidebar
• Auth pages use focused chrome (no navigation)
• PKCE auth flow, request-scoped Supabase clients, rate limiting on public abuse-prone routes

Authenticated app

• Routes under /app gated by auth middleware
• Landing page at /app
• App sidebar with App and Account sections
• user_profiles row created automatically when an auth user is created

Architecture

• Vertical feature partials (method dispatch, validation, server work, HTML fragment):
  • Public: src/pages/public-features/<feature>.astro
  • Private: src/pages/app/private-features/<feature>.astro
• Chrome modes: public, authenticated, focused
• Site identity in src/config/site.ts (name, URL, OG image, email addresses)
• Schema in supabase/migrations/ (idempotent, with RLS)
• Deploy target: Vercel (npm run build runs astro check then astro build)

Documentation and agents

• AGENTS.md — how to work in this repository
• docs/engineering/ — architecture, stack, schema, API, conventions, design, UX, security, commands, deployment, ADRs
• docs/product/ — product-specific docs
• .agents/skills/ — skills for DaisyUI, Supabase, Resend, email, delivery, and related work

Requirements

• Node.js >=22.12.0 and npm >=9.6.5 (Astro 7)
• A Supabase project
• A Resend account with a verified sending domain

Getting started

1. Install

npm install

2. Environment

cp .env.example .env

Variable	Purpose
SUPABASE_URL	Supabase project URL
SUPABASE_ANON_KEY	Publishable/anon key (RLS protects data)
RESEND_API_KEY	Server-only key for transactional email

See docs/engineering/DEPLOYMENT.md for environment notes.

3. Database

Apply the migration that creates user_profiles, RLS, and the auth trigger:

supabase link --project-ref <your-project-ref>
supabase db push

Or paste supabase/migrations/20260726170059_init_user_profiles.sql into the Supabase SQL editor. The script is idempotent.

4. Supabase Auth

1. Enable the email provider with password sign-in.
2. Add redirect URLs to the allowlist:
   • Local: http://localhost:4321/api/auth/callback
   • Production: https://<your-domain>/api/auth/callback

5. First user

/auth/signup only sends access-request emails; it does not create accounts. Create the first user in the Supabase dashboard (Authentication → Users → Add user), then sign in at /auth/signin.

6. Run

npm run dev

Open http://localhost:4321.

Rebrand

1. Edit src/config/site.ts — product name, public URL, OG image, and email addresses.
2. Replace assets in public/ (favicons, apple-touch-icon.png, android-chrome-*.png) and update public/site.webmanifest.
3. Point SITE.ogImage at a 1200×630 social image.
4. Replace placeholder copy on /, /about, and /contact.
5. Fill in docs/product/PRD.md and docs/product/FEATURES.md.
6. Set SITE.url to the production origin before deploying.

Commands

Command	Purpose
npm run dev	Dev server
npm run dev:host	Dev server on the local network
npm run build	Type-check (astro check) + production build
npm run preview	Serve the production build locally

Full list: docs/engineering/COMMANDS.md.

Documentation

Path	Contents
AGENTS.md	Working in this repo (humans and agents)
docs/engineering/	How the starter kit works
docs/product/	What is being built on top of it
.agents/skills/	Agent skills

Read AGENTS.md before changing code.

License

MIT — see LICENSE.md.