Launch Demo

Why This Guide Exists

Most template quickstarts assume you want to deploy immediately. This guide respects that you might just want to see it work first.

No configuration. No customization. No deployment. Just: “Does this thing actually run?” ✅

🎯 What You’ll Accomplish

Time Required: 5-10 minutes

• Template installed locally
• Development server running
• Demo site viewable at localhost:4321
• Ready to explore or customize

✅ Prerequisites

Already a developer? You probably have these. Quick check:

node --version && pnpm --version && git --version

New to this? You’ll need three free tools:

• Node.js 24.15.0 or newer - JavaScript runtime (the engines field enforces it; .nvmrc pins 24.21.0) (get it)
• pnpm 10+ - Fast package manager (package.json pins pnpm@11.27.1 via packageManager, so corepack enable picks up the right version)
• Git 2.30+ - Version control (get it)

⏱️ 5-10 minutes if installing from scratch

Verify Your Setup

All three installed? Run this to confirm:

node --version  # Should show v24.15.0 or higher
pnpm --version  # Should show 10.x.x or higher
git --version   # Should show 2.30.x or higher

Windows Users

For best performance:

• Use WSL (Windows Subsystem for Linux) for faster pnpm operations
• Enable long paths: git config --system core.longpaths true
• Consider using Windows Terminal for better CLI experience

⚡ Quick Start

Step 1: Create Your Project (2 min)

# Create from template (uses the latest Astro CLI)
pnpm create astro@latest my-site -- --template clownware/astro-performance-starter

# Navigate into project
cd my-site

Template Name

Replace my-site with your preferred project name. This is just a local folder name—you can change it anytime.

Pinning to a specific version? Clone at a release tag instead: git clone --branch <tag> --depth 1 https://github.com/clownware/astro-performance-starter.git my-site, then rm -rf .git && git init to start your own history.

Step 2: Install & Start Dev Server (3-5 min)

# One command to rule them all
pnpm install && pnpm run dev

# ⏱️ 3-5 minutes total
# Grab coffee ☕ — the first install takes a minute
# You'll see a localhost URL when ready

Expected Output:

🚀 astro v7.4.1 started in XXXms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose

What’s Happening?

• pnpm install - Downloads all dependencies (~2-3 minutes)
• pnpm run dev - Compiles tokens + starts dev server with hot reload (~15 seconds)

Note: The dev script automatically runs tokens:build first via a predev hook, so you don’t need to run it manually.

Step 3: Verify Installation (1 min)

1. Open browser to http://localhost:4321
2. You’ll see the starter template homepage
3. Try the showcase page: http://localhost:4321/showcase/

✅ Success! You’re locked in.

Visual confirmation: You should see a clean, modern homepage with:

• Header with navigation
• Hero section with gradient background
• Feature cards
• Dark mode toggle (try it!)

Accessibility Check

Navigate with keyboard only to verify WCAG AA compliance:

• Press Tab to move through interactive elements
• Press Enter or Space to activate buttons/links
• All interactive elements should have visible focus indicators
• Screen reader users: ARIA roles are properly implemented

🗺️ What Just Happened?

You now have:

• ✅ A complete Astro site running locally
• ✅ Live reload on every save
• ✅ Production-grade components and patterns
• ✅ A design system you can customize

But you haven’t changed anything yet. This is the template as-is. Your next move determines what you build.

💡 Before You Start Editing

Three things that’ll save you headaches:

1. Hot Reload Works - Save any file and see changes instantly (except config files)
2. Design Tokens Compile on Dev Start - pnpm run dev compiles tokens/*.json once before starting; after editing tokens, re-run pnpm run tokens:build (there’s no watcher)
3. Path Aliases FTW - Use @/components/Button not ../../components/Button

🔍 What You Have

Project Structure

TL;DR: Standard Astro project with:

• Components organized by atomic design (atoms → molecules → structural), plus Preact islands
• Type-safe content collections (blog posts, projects with validation)
• Token-based design system (change colors/fonts in one place)
• Dark-first theme (dark by default; a header toggle cycles light → dark → system, ADR-032)

Full Directory Structure

my-site/
├── src/
│   ├── components/     # UI components (atoms, molecules, structural)
│   │   ├── atoms/      # Basic elements (Button, Badge, Icon)
│   │   ├── molecules/  # Simple combos (Card, ContactForm)
│   │   ├── structural/ # Layout components (Container, Header, Footer)
│   │   └── islands/    # Interactive Preact islands
│   ├── layouts/        # Page layouts (BaseLayout.astro)
│   ├── pages/          # Routes (index.astro, 404.astro)
│   ├── content/        # Content collections (blog, projects)
│   ├── content.config.ts # Content collection schemas
│   ├── styles/         # Global styles
│   └── utils/          # Helper functions
├── public/             # Static assets (favicon, images)
├── tokens/             # Design tokens (colors, typography)
├── astro.config.mjs    # Astro configuration
└── package.json        # Dependencies and scripts

Key Features Included

Feature	Benefit
Zero-JS by default	95+ Lighthouse scores out-of-box, blazing fast load times
Token-based design	Single-file customizations (change colors/fonts in one place)
Content collections	Type-safe MDX with validation (catch errors before deploy)
Dark mode	Dark-first: renders dark until the visitor picks light with the header toggle; no flash on load
Accessibility	WCAG AA compliant components (keyboard nav, ARIA, contrast)
TypeScript	Strict mode with path aliases (catch bugs at compile time)
Tailwind CSS	Utility-first styling with design tokens (rapid prototyping)

Available Commands

pnpm run dev           # Start dev server (auto-compiles tokens first)
pnpm run build         # Build for production (env check + tokens + Astro)
pnpm run preview:build # Build + serve production build locally
pnpm run tokens:build  # Compile design tokens only (manual)
pnpm run check         # Type-check TypeScript
pnpm run format        # Format code with Biome
pnpm run lint          # Lint code with Biome

build needs SITE_URL

build and preview:build run env:validate first, which fails on a fresh clone until SITE_URL (or PUBLIC_SITE_URL) is set to a real, non-placeholder URL. pnpm run dev works without it. See Quick Deploy, Step 1.1 for setup.

🎓 Next Steps

Choose your path based on your goals:

Path A: Deploy Now ⚡

Ready to make it yours and go live?

→ Quick Deploy Guide

• Personalize branding (20-30 min)
• Deploy to production (15-20 min)
• Custom domain setup (optional)
• Total time: 45-75 minutes

Path B: Explore First 🔍

Want to understand the template before customizing?

→ Directory Structure
→ What’s Included
→ FAQ

• Learn the architecture
• Explore components
• Review design tokens
• Understand the build system

Path C: Start Building 🛠️

Jump into development immediately?

→ Creating Your First Page
→ Component Patterns
→ Content Collections

• Add new pages
• Customize components
• Work with content collections
• Build custom features

Path D: Full Implementation 📚

Want the complete guided experience?

→ Implementation Guides — one progressive path in three tiers (ADR-033)

• Foundation (Phases 0-4) ships complete in the template
• Build (Phases 5-8): components, sections, content, QA
• Polish (Phases 9-12): performance, deployment, documentation, post-launch
• Scope each phase to Essential / Recommended / Advanced and stop when you’ve reached your goals

🆘 Troubleshooting

Common Issues (80% of problems)

Port already in use

# Use a different port (works everywhere)
pnpm run dev -- --port 3000

Styles missing or broken

# Tokens auto-compile on dev start, but you can force it:
pnpm run tokens:build
pnpm run dev

Module not found errors

rm -rf node_modules pnpm-lock.yaml && pnpm install

Less Common Issues

Build fails during token compilation

Cause: Missing or corrupted token files

Fix:

# Verify token files exist
ls -la tokens/

# Should see: base.json, semantic.json
# If missing, re-clone the template

Kill process using the port (alternative)

# macOS/Linux:
lsof -ti:4321 | xargs kill -9

# Windows:
netstat -ano | findstr :4321
taskkill /PID <PID> /F

“Cannot find package ‘@astrojs/…’”

Cause: Astro integrations not installed

Fix: Reinstall dependencies (see “Module not found” above)

Red squiggly lines in VS Code

You’re seeing: TypeScript errors or warnings in your editor
Cause: Editor’s TypeScript server needs to catch up

Fix:

# Generate fresh types
pnpm run check

# Then restart TypeScript in VS Code:
# Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

Still stuck?

1. Check FAQ: Getting Started FAQ
2. Review Phase 4: Skeleton Implementation Guide
3. Search Issues: GitHub Issues
4. Ask for Help: GitHub Discussions

💡 Pro Tips

Hot Reload

Save any file → instant update. No restart needed.

What triggers reload:

• .astro, .ts, .js, .css files
• Content collections

What requires restart:

• Config files (astro.config.mjs, tsconfig.json)
• New dependencies

Design Tokens

Edit once → change everywhere. Colors, typography, and spacing are defined in tokens/ and compiled to CSS variables.

To customize:

# 1. Edit tokens/semantic.json (or tokens/base.json)
# 2. Re-run the token build — tokens compile once on dev start, not on save:
pnpm run tokens:build
# 3. The dev server hot-reloads the regenerated CSS

# For production builds, tokens compile automatically:
pnpm run build

Path Aliases

Clean imports → no more ../../ Import from anywhere using absolute paths:

import Button from '@/components/atoms/Button.astro';
import { formatDate } from '@/utils/formatDate';
import type { Feature } from '@/types/content';

Available aliases:

• @/* → src/*
• @components/* → src/components/*
• @layouts/* → src/layouts/*
• @utils/* → src/utils/*

Dark Mode

Dark-first → no config, no flash. The inline script in src/components/ThemeSetup.astro runs before paint and applies whatever is stored under the theme key in localStorage; with nothing stored it defaults to dark — it does not echo your OS prefers-color-scheme (ADR-032, dark-first amendment). Changing your OS theme therefore does nothing on a fresh visit.

To test:

1. Load http://localhost:4321 in a fresh profile or after clearing site data — it renders dark
2. Click the header theme toggle (src/components/atoms/ThemeToggle.astro): it cycles light → dark → system, writing theme=light / theme=dark to localStorage or removing the key for “system”
3. Reload — the stored choice survives; “system” (no key) falls back to dark again, by design
4. Open a second tab — the choice syncs across tabs via the storage event

🎉 You’re Ready

Your local development environment is set up and running. You can now:

• ✅ View the template at localhost:4321
• ✅ Make changes and see them live
• ✅ Explore the codebase
• ✅ Start customizing

Next: Choose your path above and let’s build.