Developer Onboarding

Project: High-performance Astro static site with Tailwind CSS, zero JavaScript by default, and 95+ Lighthouse scores enforced in CI.

Prerequisites

Before you begin, ensure you have:

• Node.js 24.15.0 or newer (install) — .nvmrc pins 24.21.0
• pnpm 10.x or later (corepack enable picks up the pnpm@11.27.1 pin from package.json)
• Git for version control
• VS Code (recommended)

Quick Start

Get up and running in 2 minutes:

# 1. Clone the repository
git clone <repository-url>
cd <project-name>

# 2. Install dependencies
pnpm install

# 3. Start development server (tokens auto-compile via the predev hook)
pnpm run dev

# 4. Open in browser
# → http://localhost:4321

Starting from the template rather than an existing project? Use the Launch Demo guide instead — it covers pnpm create astro and what to expect on first run.

Next Steps

Once you’re up and running, consider these initial configuration steps:

• Configure Analytics: This template is privacy-first. See Optional Analytics to add Plausible or Fathom.
• Customize Content: Edit the example blog posts in src/content/blog/, set SITE_URL in .env (production builds fail without it — see Quick Deploy, Step 1.1), and update your site metadata in src/config.ts.
• Review the Guides: The active-phase guides hold the current development instructions. Start with Phase 5: Components, which scopes the optional elements you can customize.

Essential Commands

# Development
pnpm run dev              # Start dev server with hot reload
pnpm run build            # Build for production (env:validate + tokens:build + astro build)
pnpm run preview          # Serve already-built dist/ locally

# Code Quality (lint-staged runs the relevant parts on commit)
pnpm run format           # Format code with Biome
pnpm run lint             # Check for code issues (Biome)
pnpm run lint:md          # Lint Markdown (markdownlint-cli2)
pnpm run check            # Type checking (astro check)
pnpm run quality          # format + lint + lint:md + check

# Design System
pnpm run tokens:build     # Rebuild design tokens
pnpm run design:validate  # Check WCAG contrast compliance

Project Structure at a Glance

src/
├── pages/        # Routes (file = URL)
├── layouts/      # Page wrappers
├── components/   # Reusable UI (Atomic Design: atoms, molecules, structural, islands, mdx)
├── content/      # Blog posts, projects, bio, experience, navigation
├── styles/       # Global CSS
└── utils/        # Helper functions

See Directory Explained for the full tree.

Architectural Notes

The Role of src/pages/index.astro

This template ships with a homepage at src/pages/index.astro. When you run pnpm dev, this is the page you will see at the root of your local server. It is a full demo page (hero, feature cards, islands, view transitions) — the smaller about.astro and contact.astro are easier starting points when you want to study a page.

• Local AI Context: The docs/ directory in this repository is not part of the production build. It exists to provide rich, local-only context for AI development assistants (ADR-034), enabling them to understand the project’s architecture and patterns. The same content is published on this site.

Development Workflow

1. Pick up a task from your project board
2. Create a branch: git checkout -b feature/your-feature
3. Make changes (hot reload will show updates)
4. Test locally: Check desktop & mobile views
5. Commit: git commit -m "feat: add new component"
   • The pre-commit hook runs lint-staged (Biome on code, markdownlint on Markdown); commit-msg runs commitlint, so the message must be a conventional commit
6. Push: git push origin feature/your-feature
7. Open PR: CI runs the quality gates, plus Lighthouse CI on the built site

See Git Workflow and Contributing for the full conventions.

Key Concepts

• Zero JS by default: We ship static HTML/CSS unless interactivity is essential (ADR-001 governs when a Preact island is justified)
• Islands Architecture: JavaScript loads only where needed
• Design Tokens: All colors, spacing, etc. come from tokens/
• Type Safety: TypeScript strict mode is enforced
• Performance First: Every PR must meet the performance budgets (budgets.json) and the Lighthouse CI floors

Common Tasks

Adding a New Page

Create a file in src/pages/ — BaseLayout requires both title and description props:

src/pages/example.astro

---
import BaseLayout from '@/layouts/BaseLayout.astro';
---

<BaseLayout title="Example Page" description="A minimal example page.">
  <h1>Hello World</h1>
</BaseLayout>

The full walkthrough, including adding the page to the header navigation, is in Creating Your First Page.

Creating a Component

Add to the appropriate atomic level:

src/components/atoms/MyButton.astro

---
export interface Props {
  variant?: 'primary' | 'secondary';
}

const { variant = 'primary' } = Astro.props;
---

<button class={variant}>
  <slot />
</button>

Working with Content

Add MDX files to src/content/blog/. The schema in src/content.config.ts requires title, description (160 characters max), date, and coverAlt; draft, featured, tags, and author have defaults:

src/content/blog/my-post.mdx

---
title: "My First Post"
description: "A short summary that doubles as the meta description."
date: 2026-01-15
coverAlt: "Describe the cover image, or the post, for assistive tech"
draft: false
---

# Hello from MDX!

This supports **markdown** and components.

See Content Collections for the full schemas.

Getting Help

• Framework Guide: See the Implementation Guides overview
• Component Docs: Browse the /showcase living style guide (pnpm dev, then open http://localhost:4321/showcase/ — ADR-049)
• GitHub Discussions: Community support (open a Discussion on your repo)

Next Steps

1. Confirm the dev server is running
2. Read the Implementation Guides overview
3. Start with Phase 5: Components - optional elements you can customize
4. Pick your first task!

---

Welcome to the team! Remember: when in doubt, check the performance budget and prefer static solutions.