Skip to content
Pulci Nella — the Clownware markPulci Nella — the Clownware markClownware Docs

Frequently Asked Questions (FAQ)

This document answers common questions about the Astro Performance Starter template.

Getting Started

Section titled “Getting Started”

What are the usage terms?

Section titled “What are the usage terms?”

This project is released under the MIT License, which means you can use it for any purpose - personal, commercial, or otherwise. You can modify, distribute, and even sell projects built with this template. No attribution required, though we always appreciate a mention!

I’m a vibecoder who uses AI agents - where do I start?

Section titled “I’m a vibecoder who uses AI agents - where do I start?”

Perfect! This template is designed for AI-assisted development. Here’s your quickstart:

  1. Point your AI agent at Phase 5 — the first phase of the Build tier. The Foundation tier (Phases 0-4) ships complete in the template; Phases 5-12 are the active build path (see the roadmap in the Implementation Guides overview)
  2. Use the Launch Demo guide to get running locally (5 minutes)
  3. Use the Quick Deploy guide for immediate deployment (45-75 minutes)
  4. Progress through other phases as your AI agent identifies needs

The documentation structure is optimized for AI context, so your agent can efficiently parse implementation guides and provide accurate assistance.

What’s included in this template?

Section titled “What’s included in this template?”

This is a production-ready foundation with:

  • Complete Astro 7.4.1 setup with zero JavaScript by default
  • 30+ UI components across atoms, molecules, structural components, and Preact islands
  • Design token system with Tailwind CSS integration
  • Performance optimization (95+ Lighthouse scores, enforced in CI — see below)
  • Accessibility compliance (WCAG AA)
  • TypeScript strict mode configuration

For a complete inventory, see What’s Included in This Template.

What deployment does the template ship?

Section titled “What deployment does the template ship?”

GitHub Pages. The repo ships one deployment pipeline, .github/workflows/deploy.yml (“Deploy to GitHub Pages”): on every push to master it builds with pnpm run build and publishes dist/ through GitHub’s Pages actions. It resolves SITE_URL for you — the default is your https://<github-username>.github.io origin with a /<repo-name> base path, and setting a SITE_URL repository variable switches the build to a custom domain served from the root. Enable Pages (Settings → Pages → Source: GitHub Actions) and push; there is nothing else to configure.

You can deploy anywhere else that builds a static site — the Quick Deploy guide walks through Cloudflare Pages as the managed-host example and covers Vercel, Netlify, and Render. The only hard requirement on any platform is that SITE_URL reaches the build, because pnpm run build runs env:validate first and fails without it.

How can I contribute?

Section titled “How can I contribute?”

We welcome contributions! You can:

  • Report bugs or suggest features via GitHub Issues
  • Submit pull requests for improvements
  • Share your sites built with this template

Contributions that improve performance, accessibility, or developer experience are especially appreciated.

Technical Questions

Section titled “Technical Questions”

What performance can I expect?

Section titled “What performance can I expect?”

The template’s headline claim is 95+ Lighthouse scores in every category, verified by a manual audit pass. CI (.github/workflows/lighthouse.yml) runs Lighthouse CI on both a desktop (lighthouserc.json) and a mobile (lighthouserc.mobile.json) profile and fails when a category drops below its floor:

  • Performance: 95+ measured (CI floor 0.90)
  • Accessibility: 95+ measured (CI floor 0.95)
  • Best Practices: 95+ measured (CI floor 0.95)
  • SEO: 95+ measured (CI floor 0.90)

The floors sit deliberately below the headline so run-to-run variance doesn’t fail builds; real regressions do (ADR-039). Actual scores vary a few points with device and network conditions.

What browsers are supported?

Section titled “What browsers are supported?”

Modern browsers with ES2022 support. The template uses:

  • CSS Grid and Flexbox (IE11+ equivalent)
  • CSS custom properties (modern browsers)
  • Progressive enhancement patterns

Legacy browser support can be added via Astro’s built-in polyfills if needed.

How do I customize the design tokens?

Section titled “How do I customize the design tokens?”

The template includes a complete design token system:

  1. Edit tokens/base.json and tokens/semantic.json
  2. Run pnpm run tokens:build to regenerate CSS variables
  3. Tokens automatically integrate with Tailwind CSS classes

This approach ensures consistent spacing, colors, and typography across your site.

How far do I need to go? (Foundation, Build, and Polish tiers)

Section titled “How far do I need to go? (Foundation, Build, and Polish tiers)”

There is one implementation path, split into three tiers that are natural stopping points (ADR-033 replaced the old dual-track model):

  • Foundation (Phases 0-4) — everyone does these; they ship pre-configured in the template
  • Build (Phases 5-8) — components, sections, content, and QA: where you make it yours
  • Polish (Phases 9-12) — performance, deployment, documentation, post-launch: production hardening

Inside each phase, tasks are labelled Essential (every project), Recommended (most projects), or Advanced (enterprise or portfolio-showcase projects). Work through the phases in order, scope each one to your needs, and stop when you’ve reached your goals.

Is this production-ready?

Section titled “Is this production-ready?”

Yes! This template is designed for production use with:

  • Security headers configured
  • Performance budgets enforced
  • Accessibility compliance built-in
  • TypeScript strict mode
  • Comprehensive testing setup

Many sites are already running in production using this foundation.

How do I get help or support?

Section titled “How do I get help or support?”
  1. Check the documentation - comprehensive guides cover most scenarios
  2. Search GitHub Issues - your question may already be answered
  3. Ask your AI agent - the docs are optimized for AI assistance
  4. Create a GitHub Issue - for bugs or missing documentation
  5. Join community discussions - check GitHub Discussions for the repository

How does this compare to other Astro starters?

Section titled “How does this compare to other Astro starters?”

This template is uniquely focused on:

  • Performance-first approach with enforceable budgets
  • AI-assisted development with optimized documentation
  • Production readiness out of the box
  • Comprehensive component system following atomic design
  • Enterprise-grade tooling (Biome, strict TypeScript, etc.)

Most other starters focus on features rather than performance and maintainability.

How do I handle Astro version upgrades?

Section titled “How do I handle Astro version upgrades?”

The template is designed to be upgrade-friendly:

  • Minimal dependencies reduce breaking change surface area
  • Standard Astro patterns align with framework evolution
  • Locked dependency versions via pnpm-lock.yaml prevent unexpected breaks (manifest ranges use ^; Tailwind CSS is pinned exactly)

Upgrade guides will be provided for major Astro releases that affect the template.