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, chrispezza.com, and the docs site — same budgets, same CI gates
  • Lighthouse 95+ performance and 98+ accessibility gated in CI, desktop and mobile
  • 61 ADRs and a layered constitution govern every architectural change
  • Companion plugin (clownware-astro-tools) on the Clownware plugin marketplace

Stack

  • Astro 6
  • 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: Architecture Is 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