ADR: Choix du Framework et du Mode de Rendu pour la Couche Présentation

Documentation technique

Statut : Accepté
Date : 2026-09-01
Auteur : [Votre Nom / Équipe d’Architecture]

1. Contexte et Problématique1/2

L’architecture globale de notre site web est structurée en trois couches distinctes. La Couche 01 (Contenu) étant définie (approche hybride Sanity.io et Astro Starlight), nous devons spécifier les fondations de la Couche 02 : Présentation (Front-end, routage et rendu utilisateur).

1. Contexte et Problématique2/2

Cette couche doit être capable de :

Consommer efficacement les fichiers locaux Markdown/MDX (Documentation Starlight).
Requéter l’API JSON de Sanity.io (Vitrine, Blog, Portfolio).
Offrir d’excellentes performances d’affichage (Score Core Web Vitals optimal) et un référencement (SEO) irréprochable.
Gérer un trafic asymétrique : des pages majoritairement statiques (blog, doc, vitrine) combinées à de potentiels besoins dynamiques futurs (recherche, formulaires complexes, interactions dynamiques ou espaces privés).

2. Décision Architecturale

Nous décidons d’adopter le framework Astro configuré en Rendu Hybride (Hybrid Rendering) pour l’ensemble de la Couche 02.

Par défaut, l’ensemble du site sera pré-généré côté serveur au moment du build (Static Site Generation - SSG). Cependant, les routes ou composants spécifiques nécessitant un calcul en temps réel ou un accès à la volée seront configurés pour s’exécuter à la demande (Server-Side Rendering - SSR).

3. Justification du choix

3.1. Pourquoi Astro ?1/2

Intégration native des sources de la Couche 01 : Astro gère nativement le concept de Content Collections (parfait pour valider et parser nos fichiers de documentation) et dispose d’une intégration officielle performante avec Sanity.
Zéro JavaScript par défaut : Pour la vitrine, la documentation et le blog, Astro génère du HTML pur. Cela garantit un chargement instantané, un avantage critique pour notre SEO et l’expérience utilisateur mobile.

3.1. Pourquoi Astro ?2/2

Architecture en Îlots (Islands) : Si une page de la vitrine ou du portfolio requiert un composant interactif complexe (ex: un carrousel, un filtre de recherche), nous pouvons l’intégrer via React, Vue ou Svelte. Astro n’hydre que cet îlot précis avec du JavaScript, préservant la légèreté du reste de la page.

3.2. Pourquoi le Rendu Hybride ?

Le mode hybride offre le meilleur des deux mondes (SSG et SSR) sur un seul et même déploiement :

Performance et Coût (SSG par défaut) : Les sections Blog, Portfolio, Vitrine et Documentation changent peu fréquemment. Elles sont compilées en fichiers HTML statiques au build. L’affichage est immédiat et l’hébergement sur un CDN mondial est extrêmement économique.
Flexibilité Évolutive (SSR à la demande) : En exportant simplement export const prerender = false; sur une route spécifique, Astro bascule cette page en rendu dynamique. Cela nous permet de gérer sans effort des fonctionnalités serveurs (ex: traitement de formulaires, pages de recherche dynamique, ou intégration future avec la Couche 03).

4. Conséquences de la décision

Effets Positifs (Avantages)

Performances maximales : Les pages statiques sont servies directement depuis la couche CDN la plus proche de l’utilisateur.
Unification de la stack : Starlight s’intègre parfaitement puisque c’est une extension officielle d’Astro. Le site principal et la documentation partagent le même moteur de rendu et les mêmes configurations globales (Tailwind CSS, TypeScript, etc.).
Flexibilité des frameworks UI : L’équipe de développement peut utiliser le framework JS de son choix (ou aucun) au sein des îlots d’interactivité.

Effets Négatifs (Inconvénients & Risques)

Complexité d’hébergement : Le rendu hybride nécessite un hébergeur doté d’un environnement d’exécution serveur ou Serverless (ex: Vercel, Netlify, Cloudflare Pages, ou un serveur Node.js/Docker) pour traiter les routes SSR. Un simple hébergement de fichiers statiques (S3 standard) ne suffit plus.
Gestion de l’hydratation : Les développeurs doivent maîtriser les directives d’hydratation d’Astro (client:load, client:visible, etc.) pour éviter de charger du JavaScript inutilement.

5. Alternatives Exclues

Astro en mode SSG Strict (Static) : Exclu car cela nous aurait bloqués ou contraints à des contournements complexes (appels API côté client uniquement) le jour où le site aura besoin de routes dynamiques ou d’interactions serveurs temps réel.
Next.js ou Nuxt (Full SSR/ISR) : Exclus car ces frameworks envoient systématiquement une quantité importante de JavaScript au navigateur (Framework Runtime) pour réhydrater l’ensemble de la page, ce qui est contre-productif pour un site à forte dominante de contenu (doc, blog, vitrine) où Astro est intrinsèquement plus rapide.