Reference

Static Site Stack Boundaries

Reference boundaries for Astro static sites — env vars, content collections, deploy, and handoff conventions.

  • astro
  • tailwind
  • deploy
Raw markdown Manifest JSON ← Agent Kit

Suggested Cursor path: .cursor/rules/davidcole-stack-boundaries.mdc

Static Site Stack Boundaries (davidcole.cloud reference)

Use this when bootstrapping a Gnomad-style Astro site. Adapt stack lines for other projects; keep the env and verify patterns.

Stack defaults

  • Astro 6 static export (output: 'static')
  • React islands only where interactivity is required
  • TypeScript, Tailwind CSS v4, MDX content collections
  • Node.js ≥ 22.12.0

Environment & secrets

  • Never commit .env
  • Client-visible config: PUBLIC_* prefix only
  • Document new public env vars in .env.example and README
  • CI must inject production PUBLIC_* vars at build time

Content collections

  • Validate frontmatter with Zod in content.config.ts
  • Use draft: true for WIP; filter with !data.draft in queries

Deploy (GitHub Pages pattern)

  • Workflow on main builds dist/ and deploys to Pages
  • Custom domain via public/CNAME
  • Do not force-push main

Handoff

See Handoff Checklist before calling a client site “done.”