Astro v6 Architecture Rules (Strict Mode)

1. Core Philosophy

• Follow Astro’s “HTML-first / zero JavaScript by default” principle:

  • Everything is static HTML unless interactivity is explicitly required.
  • JavaScript is a cost → only add when it creates real user value.

• Always think in “Islands Architecture”:

  • The page is static HTML
  • Interactive parts are isolated islands
  • Never treat the whole page as an app

• Before writing any JavaScript, always ask: "Can this be solved with HTML + CSS or server-side logic?"

---

2. Component Model

• Use .astro components for:

  • Layout
  • Composition
  • Static UI
  • Data fetching
  • Server-side logic (frontmatter)

• .astro components:

  • Run at build-time or server-side
  • Do NOT ship JavaScript by default
  • Must remain framework-agnostic

• NEVER use React/Vue/Svelte hooks inside .astro

---

3. Islands (Interactive Components)

• Only use framework components (React, Vue, Svelte, etc.) for interactivity.

• Treat every interactive component as an isolated island:

  • Independent
  • Self-contained
  • Minimal scope

• NEVER:

  • Hydrate entire pages or layouts
  • Wrap large trees in a single island
  • Create many small islands in loops unnecessarily

• Prefer:

  • Static list rendering
  • Hydrate only the minimal interactive unit

---

4. Hydration Strategy (Critical)

• Always explicitly define hydration using client:* directives.

• Choose the LOWEST possible priority:

  • client:load → Only for critical, above-the-fold interactivity

  • client:idle → For secondary UI after page load

  • client:visible → For below-the-fold or heavy components

  • client:media → For responsive / conditional UI

  • client:only → ONLY when SSR breaks (window, localStorage, etc.)

• Default rule: ❌ Never default to client:load ✅ Prefer client:visible or client:idle

• Hydration is a performance budget:

  • Every island adds JS
  • Keep total JS minimal

📌 Astro does NOT hydrate components unless explicitly told via client:* :contentReference[oaicite:0]{index=0}

---

5. Server vs Client Logic

• Prefer server-side logic (inside .astro frontmatter) for:

  • Data fetching
  • Transformations
  • Filtering / sorting
  • Derived values

• Only use client-side state when:

  • User interaction requires it
  • Real-time updates are needed

• Avoid:

  • Duplicating logic on client
  • Moving server logic into islands

---

6. State Management

• Avoid client state unless strictly necessary.

• If needed:

  • Scope state inside the island only
  • Do NOT create global app state unless required

• For cross-island state:

  • Use lightweight shared stores (e.g., nano stores)
  • Avoid heavy global state systems by default

---

7. Performance Constraints (Hard Rules)

• Minimize JavaScript shipped to client:

  • Astro only loads JS for hydrated components :contentReference[oaicite:1]{index=1}

• Prefer:

  • Static rendering
  • Partial hydration
  • Lazy hydration

• Avoid:

  • Hydrating large lists
  • Repeated islands in loops
  • Overusing client:load

• Each island:

  • Has its own bundle
  • Loads independently
  • Should remain small and focused :contentReference[oaicite:2]{index=2}

---

8. File & Project Structure

• /pages

  • Entry points (SSG/SSR)
  • No client logic

• /components

  • Shared UI
  • Islands live here

• /layouts

  • Static wrappers only

• /content

  • Markdown / CMS data

• Keep .astro files focused on composition, not behavior

---

9. Anti-Patterns (Strictly Forbidden)

• ❌ Using hooks in .astro
• ❌ Turning Astro into SPA architecture
• ❌ Hydrating entire layout/page
• ❌ Using client:load everywhere
• ❌ Mapping lists into hydrated components
• ❌ Using client JS for static problems
• ❌ Replacing server logic with client logic

---

10. Preferred Patterns

• ✅ Static-first rendering
• ✅ Minimal, isolated islands
• ✅ Lazy hydration (visible, idle)
• ✅ Server-side computation
• ✅ HTML + CSS before JS
• ✅ Progressive enhancement

---

11. Decision Framework (VERY IMPORTANT)

For every feature:

1. Can this be static HTML? → YES → Use .astro

2. Does it require interaction? → NO → Stay static

3. Does it require JS? → YES → Create an island

4. When should it load? → Choose LOWEST priority client:*

---

12. Mental Model (Non-Negotiable)

• Astro is NOT:

  • Next.js
  • SPA framework
  • React-first system

• Astro IS:

  • Static-first renderer
  • Partial hydration system
  • Performance-first architecture

• Think: ❌ “Build an app” ✅ “Ship HTML + sprinkle JS”