Astro v6 Architecture Rules (Strict Mode)

# 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 ## 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 - 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 ## 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: "Ship HTML + sprinkle JS"

Astro v6 Architecture Rules (Strict Mode)

Prompt ContentSave

Usage

References

Talk