# 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”