@cds/astro-starter

Production-grade Astro 5 boilerplate: server-rendered, reusable .astro-first component system, island-native state, markdown content negotiation for AI agents, llms.txt, and a green Lighthouse audit baked in.

Features

• Astro 5 SSR via @astrojs/node (standalone). Marketing pages prerender to static HTML; dynamic routes run at request time.
• Reusable component system — .astro-first primitives with class-variance-authority variants and a cn() helper (clsx + tailwind-merge). Zero JS by default.
• React islands for interactivity only, hydrated off the critical path.
• Island-native state/data — nanostores + @nanostores/query. Singleton stores share one cache across islands, no provider tree.
• Markdown content negotiation — same URL serves HTML to browsers and raw markdown to agents sending Accept: text/markdown (RFC 9110 aware).
• llms.txt + llms-full.txt generated from the docs collection at build.
• Tailwind v4, TypeScript strict, ESLint, Prettier.
• AI agent guidance in .agents/ so beginners and agents follow the rules and keep the audit green.

Quick start

bun install
bun dev              # http://localhost:4321

Scripts

Command	What it does
bun dev	Dev server
bun run build	Generate llms.txt, then astro build
bun run preview	Preview the production build
bun run lint	ESLint
bun run format	Prettier
bun run gen:llms	Regenerate llms.txt only

The Lighthouse audit is run by an AI agent via the chrome-devtools MCP (lighthouse_audit) against bun run preview, not a CLI dependency. See .agents/skills/keep-audit-green.

Project structure

src/
  components/ui/        # primitives (.astro + cva), zero JS
  components/sections/  # composite blocks
  components/islands/   # React islands (the only JS shipped)
  lib/                  # cn() + shared cva variants
  stores/               # nanostores state + @nanostores/query fetchers
  content/docs/         # markdown collection (HTML or raw markdown)
  content.config.ts     # collection schema
  middleware.ts         # Accept-header content negotiation
  layouts/  i18n/  pages/
scripts/gen-llms.mjs    # llms.txt generator (prebuild)
.agents/                # AGENTS.md + skills for AI agents
docs/                   # ARCHITECTURE.md, CONVENTIONS.md, plans

Content negotiation

# Browser gets rendered HTML
curl http://localhost:4321/docs/getting-started/

# Agent gets raw markdown
curl -H "Accept: text/markdown" http://localhost:4321/docs/getting-started/
# Content-Type: text/markdown; charset=utf-8
# Vary: Accept

Design system and rebranding

Design is centralized so rebranding never touches component code:

• Tokens (colors, fonts): src/styles/global.css under @theme.
• Brand (name, URL, social, OG image): src/lib/site.ts (SITE.brand).
• Variants: src/lib/variants/ (shared cva defs).
• Copy: src/i18n/en.json and id.json.

To rebrand: edit SITE.brand and tokens, swap public/og-default.png and public/favicon.svg, update i18n copy. See .agents/skills/apply-design-system.

Working in this repo

Read .agents/AGENTS.md. It defines the rules that keep the audit green: primitives are .astro, only islands ship JS, prefer client:visible, islands read from stores, run the audit before done.

AI agent skills

Task skills live in .agents/skills/: apply-design-system, add-ui-primitive, add-island, add-content-doc, keep-audit-green. They are plain markdown, committed to the repo, so there is nothing to install beyond cloning. To make an agent discover them automatically:

# Claude Code project skills
mkdir -p .claude/skills && cp -r .agents/skills/* .claude/skills/

For pi, Cursor, Windsurf, or any other harness, point its rules/skills path at .agents/AGENTS.md (the skill catalog) and .agents/skills/. See the "Skills (for AI agents)" section in AGENTS.md for per-tool wiring.

i18n

English (default, no prefix) and Indonesian (/id/), configured in astro.config.mjs and src/i18n/.

License

MIT