Règles d'architecture Astro v6 (Mode strict)

# Règles d'architecture Astro v6 (Mode strict) ## 1. Philosophie de base - Suivre le principe "HTML-first / zéro JavaScript par défaut" d'Astro : - Tout est HTML statique, sauf si l'interactivité est explicitement requise. - JavaScript est un coût, ne l'ajouter que lorsqu'il crée une réelle valeur utilisateur. - Toujours penser en "Architecture en îles" : - La page est du HTML statique - Les parties interactives sont des îles isolées - Ne jamais traiter la page entière comme une application - Avant d'écrire du JavaScript, toujours se demander : "Ce problème peut-il être résolu avec HTML + CSS ou une logique côté serveur ?" ## 2. Modèle de composants - Utiliser les composants `.astro` pour : - La mise en page - La composition - L'interface statique - La récupération de données - La logique côté serveur (frontmatter) - Composants `.astro` : - S'exécutent au moment de la construction ou côté serveur - N'expédient PAS de JavaScript par défaut - Doivent rester agnostiques aux frameworks - Ne JAMAIS utiliser de hooks React/Vue/Svelte dans `.astro` ## 3. Îles (composants interactifs) - Utiliser uniquement des composants de framework (React, Vue, Svelte, etc.) pour l'interactivité. - Traiter chaque composant interactif comme une île isolée : - Indépendante - Autonome - Portée minimale - Ne JAMAIS : - Hydrater des pages ou des mises en page entières - Envelopper de grands arbres dans une seule île - Créer de nombreuses petites îles dans des boucles inutilement - Préférer : - Le rendu de listes statiques - Hydrater uniquement l'unité interactive minimale ## 4. Stratégie d'hydratation (critique) - Toujours définir explicitement l'hydratation avec les directives `client:*`. - Choisir la priorité la PLUS BASSE possible : - `client:load` -> Uniquement pour l'interactivité critique au-dessus de la ligne de flottaison - `client:idle` -> Pour l'interface secondaire après le chargement de la page - `client:visible` -> Pour les composants sous la ligne de flottaison ou lourds - `client:media` -> Pour l'interface réactive / conditionnelle - `client:only` -> UNIQUEMENT lorsque le SSR casse (window, localStorage, etc.) - Règle par défaut : - Ne jamais utiliser `client:load` par défaut - Préférer `client:visible` ou `client:idle` - L'hydratation est un budget de performance : - Chaque île ajoute du JavaScript - Garder le JavaScript total minimal ## 5. Logique serveur vs client - Préférer la logique côté serveur (dans le frontmatter `.astro`) pour : - La récupération de données - Les transformations - Le filtrage / tri - Les valeurs dérivées - Utiliser l'état côté client uniquement lorsque : - L'interaction utilisateur l'exige - Des mises à jour en temps réel sont nécessaires - Éviter : - De dupliquer la logique côté client - De déplacer la logique serveur dans les îles ## 6. Gestion d'état - Éviter l'état client sauf si strictement nécessaire. - Si nécessaire : - Limiter l'état à l'intérieur de l'île uniquement - Ne PAS créer d'état applicatif global sauf si requis - Pour l'état entre îles : - Utiliser des stores partagés légers (par exemple, nano stores) - Éviter les systèmes d'état global lourds par défaut ## 7. Contraintes de performance (règles strictes) - Minimiser le JavaScript expédié au client : - Astro ne charge le JavaScript que pour les composants hydratés - Préférer : - Le rendu statique - L'hydratation partielle - L'hydratation paresseuse - Éviter : - D'hydrater de grandes listes - Les îles répétées dans des boucles - La surutilisation de `client:load` - Chaque île : - Possède son propre bundle - Se charge indépendamment - Doit rester petite et ciblée ## 8. Structure des fichiers et du projet - `/pages` - Points d'entrée (SSG/SSR), aucune logique client - `/components` - Interface partagée, les îles vivent ici - `/layouts` - Uniquement des wrappers statiques - `/content` - Données Markdown / CMS - Garder les fichiers `.astro` axés sur la composition, pas sur le comportement ## 9. Anti-modèles (strictement interdits) - Utiliser des hooks dans `.astro` - Transformer Astro en architecture SPA - Hydrater une mise en page ou une page entière - Utiliser `client:load` partout - Mapper des listes vers des composants hydratés - Utiliser du JavaScript client pour des problèmes statiques - Remplacer la logique serveur par la logique client ## 10. Modèles préférés - Rendu statique en premier - Îles minimales et isolées - Hydratation paresseuse (`visible`, `idle`) - Calcul côté serveur - HTML + CSS avant JavaScript - Amélioration progressive ## 11. Cadre de décision (TRÈS IMPORTANT) Pour chaque fonctionnalité : 1. Cela peut-il être du HTML statique ? -> OUI -> Utiliser `.astro` 2. Cela nécessite-t-il une interaction ? -> NON -> Rester statique 3. Cela nécessite-t-il du JavaScript ? -> OUI -> Créer une île 4. Quand doit-il se charger ? -> Choisir la priorité la PLUS BASSE `client:*` ## 12. Modèle mental (non négociable) - Astro n'est PAS : - Next.js - Un framework SPA - Un système React-first - Astro EST : - Un rendu statique en premier - Un système d'hydratation partielle - Une architecture axée performance - Penser : "Expédier du HTML + saupoudrer du JavaScript"