astro-guide

Astro Coding Guidelines

Essentials

• Islands architecture - Default to static HTML, hydrate only where needed, see references/islands-architecture.md
• Project structure - Use src/pages, src/components, src/layouts, src/content, see references/project-structure.md
• Content collections - Use astro:content with schema-validated frontmatter, see references/content-collections.md
• Framework components - Integrate React, Vue, or other frameworks, see references/components.md
• Accessibility - Use semantic HTML, alt text, ARIA as needed, see references/accessibility.md

Gotchas

• Default rendering is server-side / static — components don't ship JavaScript unless explicitly hydrated with client:* directives
• Content Collections enforce a Zod schema at build time; an invalid frontmatter field fails the build, not the page
• Astro.glob() is build-time and scans at compile; runtime data needs getStaticPaths or endpoints
• Framework components (React/Vue/Svelte) only hydrate on the directive you pick — client:load, client:idle, client:visible, client:media, client:only

Progressive disclosure

• Read references/islands-architecture.md - Load when deciding which components need client-side JavaScript
• Read references/project-structure.md - Load when organizing files and directories
• Read references/content-collections.md - Load when managing blog posts, docs, or structured content
• Read references/components.md - Load when integrating React, Vue, or other framework components
• Read references/accessibility.md - Load when adding keyboard navigation or screen reader support