Dev Tools

Astro Performance Starter

The flagship Clownware template: performance budgets in CI, zero-JS discipline, and an AI context system no other Astro starter ships.

Role · Creator and maintainer

View liveSourceDocs

Outcomes

  • Powers clownware.org and chrispezza.com: same budgets, same CI gates
  • Lighthouse floors gated in CI on desktop and mobile: performance 90, accessibility 95, best practices 95, SEO 90
  • 70 ADRs, a layered constitution, and 42 automated enforcement checks (29 blocking) govern every architectural change
  • Companion plugin (clownware-astro-tools) on the Clownware plugin marketplace

Stack

  • Astro 7
  • TypeScript
  • Tailwind CSS 4
  • Biome
  • Playwright
  • Lighthouse CI

Context

The flagship template from Clownware, my open-source studio. Most starters optimize for demo appeal: animated landing pages that fall apart the moment you build something real on them.

The Problem

No Astro starter was built for the two things that actually matter over a project’s life: performance discipline (not just a good first score) and AI-assisted development as a first-class workflow.

My Role

Creator and maintainer. Every architectural decision is mine, recorded in the ADR log rather than in my head.

Approach

  • Performance budgets enforced in CI. JavaScript under 160KB raw, CSS under 50KB, per-image caps, a two-preload font budget, and Lighthouse gates on desktop and mobile. Budgets you can’t merge past, not aspirations.
  • Zero-JS-by-default islands discipline. client:load is forbidden without a written ADR justification.
  • An AI context system as the differentiator. A layered CLAUDE.md constitution with halt-on-violation rules, an AI context index, 13-phase implementation docs, and a published prompt library. The repo is designed for agents to work in safely.
  • The starter-vs-framework tension, resolved. The clone stays lean; the richness lives in an external docs site.
  • Design tokens as the styling contract. A base/semantic token pipeline, the same pipeline this site’s Pezza design system plugs into.

The discipline running through this approach is the site’s thesis: Decisions Are the Interface Now.

What I’d Do Differently

Ship the docs site earlier. The template carried its documentation in-repo for too long, and splitting it out is what finally made the clone feel light.

All work