Astro v6 Architekturregeln (Strict Mode)

# Astro v6 Architekturregeln (Strikter Modus) ## 1. Kernphilosophie - Befolge Astros Prinzip "HTML-first / null JavaScript standardmäßig": - Alles ist statisches HTML, es sei denn, Interaktivität wird ausdrücklich benötigt. - JavaScript ist ein Kostenfaktor, füge es nur hinzu, wenn es echten Nutzen für den Benutzer schafft. - Denke immer in der "Insel-Architektur": - Die Seite ist statisches HTML - Interaktive Teile sind isolierte Inseln - Behandle niemals die gesamte Seite als App - Bevor du JavaScript schreibst, frage dich immer: "Kann das mit HTML + CSS oder serverseitiger Logik gelöst werden?" ## 2. Komponentenmodell - Verwende `.astro`-Komponenten für: - Layout - Komposition - Statische UI - Datenabruf - Serverseitige Logik (Frontmatter) - `.astro`-Komponenten: - Laufen zur Build-Zeit oder serverseitig - Liefern standardmäßig KEIN JavaScript aus - Müssen framework-agnostisch bleiben - Verwende NIEMALS React/Vue/Svelte-Hooks innerhalb von `.astro` ## 3. Inseln (Interaktive Komponenten) - Verwende Framework-Komponenten (React, Vue, Svelte usw.) nur für Interaktivität. - Behandle jede interaktive Komponente als isolierte Insel: - Unabhängig - In sich geschlossen - Minimaler Umfang - NIEMALS: - Ganze Seiten oder Layouts hydratisieren - Große Bäume in eine einzige Insel packen - Unnötig viele kleine Inseln in Schleifen erstellen - Bevorzuge: - Statisches Rendern von Listen - Nur die minimale interaktive Einheit hydratisieren ## 4. Hydratisierungsstrategie (Kritisch) - Definiere Hydratisierung immer explizit mit `client:*`-Direktiven. - Wähle die NIEDRIGSTE mögliche Priorität: - `client:load` -> Nur für kritische Interaktivität oberhalb des Falzes - `client:idle` -> Für sekundäre UI nach dem Laden der Seite - `client:visible` -> Für unterhalb des Falzes oder schwere Komponenten - `client:media` -> Für responsive / bedingte UI - `client:only` -> NUR wenn SSR bricht (window, localStorage usw.) - Standardregel: - Standardmäßig niemals `client:load` verwenden - `client:visible` oder `client:idle` bevorzugen - Hydratisierung ist ein Leistungsbudget: - Jede Insel fügt JavaScript hinzu - Halte das gesamte JavaScript minimal ## 5. Server- vs. Client-Logik - Bevorzuge serverseitige Logik (innerhalb des `.astro`-Frontmatters) für: - Datenabruf - Transformationen - Filtern / Sortieren - Abgeleitete Werte - Verwende clientseitigen Zustand nur, wenn: - Benutzerinteraktion ihn erfordert - Echtzeit-Updates benötigt werden - Vermeide: - Logik auf dem Client zu duplizieren - Serverlogik in Inseln zu verschieben ## 6. Zustandsverwaltung - Vermeide Client-Zustand, es sei denn, er ist unbedingt notwendig. - Falls benötigt: - Begrenze den Zustand auf die Insel selbst - Erstelle KEINEN globalen App-Zustand, es sei denn, er ist erforderlich - Für zustandsübergreifende Inseln: - Verwende leichtgewichtige gemeinsame Stores (z. B. Nano-Stores) - Vermeide standardmäßig schwere globale Zustandssysteme ## 7. Leistungsbeschränkungen (Harte Regeln) - Minimiere das an den Client gelieferte JavaScript: - Astro lädt nur JavaScript für hydratisierte Komponenten - Bevorzuge: - Statisches Rendern - Partielle Hydratisierung - Lazy Hydratisierung - Vermeide: - Das Hydratisieren großer Listen - Wiederholte Inseln in Schleifen - Übermäßige Verwendung von `client:load` - Jede Insel: - Hat ihr eigenes Bundle - Lädt unabhängig - Sollte klein und fokussiert bleiben ## 8. Datei- & Projektstruktur - `/pages` - Einstiegspunkte (SSG/SSR), keine Client-Logik - `/components` - Geteilte UI, Inseln leben hier - `/layouts` - Nur statische Wrapper - `/content` - Markdown / CMS-Daten - Halte `.astro`-Dateien auf Komposition fokussiert, nicht auf Verhalten ## 9. Anti-Patterns (Streng verboten) - Hooks in `.astro` verwenden - Astro in eine SPA-Architektur verwandeln - Das gesamte Layout/die gesamte Seite hydratisieren - `client:load` überall verwenden - Listen in hydratisierte Komponenten mappen - Client-JavaScript für statische Probleme verwenden - Serverlogik durch Clientlogik ersetzen ## 10. Bevorzugte Muster - Statisches Rendering zuerst - Minimale, isolierte Inseln - Lazy Hydratisierung (`visible`, `idle`) - Serverseitige Berechnung - HTML + CSS vor JavaScript - Progressive Enhancement ## 11. Entscheidungsrahmen (SEHR WICHTIG) Für jede Funktion: 1. Kann das statisches HTML sein? -> JA -> Verwende `.astro` 2. Erfordert es Interaktion? -> NEIN -> Bleibe statisch 3. Erfordert es JavaScript? -> JA -> Erstelle eine Insel 4. Wann sollte es laden? -> Wähle die NIEDRIGSTE Priorität `client:*` ## 12. Mentales Modell (Nicht verhandelbar) - Astro ist NICHT: - Next.js - SPA-Framework - React-first-System - Astro IST: - Statischer Renderer zuerst - Partielles Hydratisierungssystem - Leistungsorientierte Architektur - Denke: "HTML ausliefern + JavaScript darüber streuen"