Astro Best Practices

Use this skill as the baseline when designing, implementing, or reviewing Astro work. It translates Astro-specific architectural guidance into portable instructions that can be applied across agents.

Core Principles

• prefer static generation when request-time rendering is not necessary
• keep client-side JavaScript minimal
• use framework islands only for real interactivity
• preserve clear project structure and predictable routing
• optimize for accessibility and maintainability, not just output parity

Architecture Defaults

Prefer .astro first

• use .astro components for static and mostly static UI
• reach for React, Vue, or another framework only when local state or client-side behavior is genuinely needed
• keep interactive islands small and leaf-like