ADR: Correction du Mode Hybride Astro (Static par défaut, SSR à la demande)

Statut : Accepté
Date : 2026-09-16
Auteur : Devin

1. Contexte et Problématique

L’ADR L2 définissait l’utilisation du Rendu Hybride (Hybrid Rendering) pour la couche Présentation, avec un mélange de SSG (par défaut) et SSR (à la demande).

L’implémentation initiale utilisait le mode SSR pur (output: 'server'), sans utiliser le mode hybride correct d’Astro. Suite à une révision et à la consultation de la documentation officielle Astro, l’implémentation a été corrigée pour utiliser le mode hybride correct : static par défaut, SSR à la demande via export const prerender = false.

2. Décision Architecturale

Nous décidons d’utiliser le mode hybride correct d’Astro avec l’adaptateur Cloudflare :

Configuration dans astro.config.mjs :

export default defineConfig({
  output: 'server',  // Hybride : static par défaut, SSR à la demande via prerender = false
  adapter: cloudflare({
    imageService: 'passthrough',
    prerenderEnvironment: 'node',
  }),
  // ...
});

Mode hybride :

Par défaut : les pages sont pré-rendues en static (SSG) au build
À la demande : les pages avec export const prerender = false sont rendues en SSR

3. Justification du choix

3.1. Pourquoi le mode hybride ?

Documentation officielle Astro : La documentation officielle recommande cette approche pour les sites avec un mix de contenu statique et dynamique.
Performance optimisée : Le contenu statique est pré-rendu pour une performance maximale, le contenu dynamique est rendu à la demande.
Support du mode Preview : Le mode SSR à la demande supporte le mode preview Sanity via prerender = false.
Compatibilité Cloudflare : L’adaptateur Cloudflare supporte parfaitement ce mode hybride.

3.2. Pourquoi `output: 'server'` ?

Adaptateur Cloudflare : L’adaptateur Cloudflare force output: 'server' pour le rendu à la demande.
Mode hybride via prerender : Le mode hybride est réalisé via export const prerender = true/false sur les pages individuelles, pas via output: 'static'.
Documentation Astro : La documentation officielle indique que output: 'server' avec un adaptateur permet le mode hybride via prerender.

4. Conséquences de la décision

Effets Positifs (Avantages)

Alignement avec l’ADR L2 : L’implémentation correspond maintenant à la décision architecturale documentée.
Performance optimisée : Le contenu statique est pré-rendu pour une performance maximale.
Support du mode Preview : Le mode SSR à la demande supporte le mode preview Sanity.
Flexibilité : Les pages peuvent être statiques ou dynamiques selon les besoins.

Effets Négatifs (Inconvénients & Risques)

Complexité de configuration : Les pages doivent être explicitement configurées avec prerender = true/false.
Débogage : Le mode hybride peut être plus complexe à déboguer si la configuration prerender est incorrecte.
Build plus long : Le build doit pré-rendre les pages statiques, ce qui peut augmenter le temps de build.

5. Alternatives Exclues

Mode SSR pur : Exclu car non optimal pour le contenu statique.
Mode SSG pur : Exclu car ne supporte pas le mode preview Sanity facilement.
Mode SSR avec middleware : Exclu car ajoute de la complexité inutile.

6. Recommandations

Documenter les prerender : Documenter clairement quelles pages utilisent prerender = true et lesquelles utilisent prerender = false.
Surveiller les performances : Surveiller les performances pour détecter si le mode hybride est optimal.
Tests : Tester le mode preview et les routes dynamiques pour s’assurer qu’elles fonctionnent correctement.