[Nom de la Route]

[Nom de la Route]

Documentation technique

Type de ressource : Route Astro (Page SSG / Page SSR / Endpoint API)
Fichier source : src/pages/[chemin].astro ou src/pages/api/[endpoint].ts
Statut : [Actif / Déprécié / En développement]

1. Vue d’ensemble

1.1. Description

[Description concise du rôle de cette route dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. afficher la liste des articles de blog]
• [Bénéfice pour l’utilisateur final]

1.3. Caractéristiques

Propriété	Valeur
URL publique	/[chemin]
Mode de rendu	[SSG / SSR / Hybride]
Type	[Page HTML / Endpoint JSON / Redirect]
Méthode HTTP	[GET / POST / Les deux]
Authentification requise	[Oui / Non / Preview uniquement]
Cache	[Voir §6]

2. Architecture et flux

2.1. Diagramme de flux

[Requête utilisateur]
     │
     ▼
[Cloudflare Pages / Edge]
     │  • Middleware global (CSP, cookies)
     │  • Routage vers Astro
     ▼
[Astro Route]
     │  • getStaticPaths (si SSG dynamique)
     │  • Récupération des données (Sanity / local)
     │  • Rendu du composant
     ▼
[Réponse HTML / JSON]

2.2. Composants impliqués

Composant	Rôle	Couche
Fichier .astro ou .ts	Définition de la route	L2 (Astro)
getSanityClient()	Récupération des données CMS	L2 (Astro)
Composants UI	Rendu visuel	L2 (Astro)
Layout	Structure HTML globale	L2 (Astro)
Middleware Cloudflare	Sécurité + Preview cookie	L3 (Cloudflare)

3. Implémentation

3.1. Code de la route1/2

3.1. Code de la route2/2

src/pages/[chemin].astro

---
import BaseLayout from '../layouts/BaseLayout.astro';
import { getSanityClient } from '../lib/sanity';
import type { [TypeName] } from '../types/sanity';

// Configuration du rendu
export const prerender = true; // ou false pour SSR

// Génération des chemins statiques (si SSG dynamique)
export async function getStaticPaths() {
  const client = getSanityClient(/* ... */);
  const items = await client.fetch(`*[_type == "[type]" && status == "published"]{
    slug
  }`);

  return items.map(item => ({
    params: { slug: item.slug.current },
  }));
}

// Récupération des données
const { slug } = Astro.params;
const client = getSanityClient(Astro);
const data = await client.fetch<[TypeName]>(`*[_type == "[type]" && slug.current == $slug][0]{
  ...,
  author->{name, image},
  categories[]->{title, slug}
}`, { slug });

// Gestion du 404
if (!data) {
  return Astro.redirect('/404');
}
---

<BaseLayout title={data.title} description={data.seo?.metaDescription}>
  <!-- Contenu de la page -->
  <h1>{data.title}</h1>
  <!-- ... -->
</BaseLayout>

3.2. Variante : Endpoint API (SSR)

src/pages/api/[endpoint].ts

export const prerender = false; // SSR obligatoire

export async function GET({ request, cookies, params }: APIContext) {
  // Logique de l'endpoint
  const data = { /* ... */ };

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'public, max-age=60',
    },
  });
}

export async function POST({ request }: APIContext) {
  const body = await request.json();
  // Traitement du formulaire ou de l'action
  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
}

3.3. Variante : Page SSR avec mode Preview

src/pages/[chemin].astro

---
export const prerender = false; // SSR pour supporter la preview

import { getSanityClient } from '../lib/sanity';

const client = getSanityClient(Astro); // Détection auto du mode preview
const data = await client.fetch(/* GROQ query */);
---

4. Données et requêtes GROQ

4.1. Requête principale

*[_type == "[type]" && slug.current == $slug][0]{
  _id,
  title,
  slug,
  publishedAt,
  mainImage {
    url,
    metadata { dimensions, alt }
  },
  body,
  seo {
    metaTitle,
    metaDescription,
    ogImage
  }
}

4.2. Requêtes secondaires (si applicable)

Requête	Description	Paramètres
[Nom]	[Description]	[Paramètres]

4.3. Types TypeScript associés

// Type généré par sanity-typegen
export type [TypeName] = {
  _id: string;
  _type: '[type]';
  title: string;
  slug: { _type: 'slug'; current: string };
  // ... autres champs
};

5. Paramètres et validation

5.1. Paramètres d’URL

Paramètre	Type	Obligatoire	Description	Validation
slug	string	✅	Identifiant de la page	^[a-z0-9-]+$
[Autre]	[Type]	[✅/❌]	[Description]	[Règle]

5.2. Query strings (si applicable)

Paramètre	Type	Obligatoire	Description	Valeur par défaut
page	number	❌	Pagination	1
category	string	❌	Filtre par catégorie	all

5.3. Gestion des erreurs

Code HTTP	Condition	Réponse
200	Succès	Page HTML / JSON
301	Slug modifié (redirect permanent)	Redirection vers nouveau slug
307	Preview redirect	Redirection temporaire
404	Document non trouvé	Page 404 personnalisée
500	Erreur serveur (Sanity indisponible)	Page d’erreur générique

6. Stratégie de cache

6.1. En-têtes de cache

Mode	Cache-Control	CDN-Cache-Control	Rationale
SSG (build time)	public, max-age=31536000, immutable	public, max-age=31536000	Contenu statique, invalidé au rebuild
SSR standard	public, max-age=60	max-age=300, stale-while-revalidate=86400	Contenu semi-dynamique
SSR Preview	no-store, no-cache, must-revalidate, private	no-store	Contenu draft, jamais en cache
Endpoint API	public, max-age=300	max-age=600	Données JSON
POST (actions)	no-store	no-store	Jamais en cache

6.2. Implémentation dans la route

---
// SSG : pas besoin de headers (géré par Cloudflare Pages)
export const prerender = true;

// SSR : configuration explicite
export const prerender = false;
Astro.response.headers.set('Cache-Control', 'public, max-age=60');
Astro.response.headers.set('CDN-Cache-Control', 'max-age=300, stale-while-revalidate=86400');

// Preview : bypass total
const isPreview = Astro.cookies.get('sanity-preview')?.value === 'true';
if (isPreview) {
  Astro.response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, private');
  Astro.response.headers.set('CDN-Cache-Control', 'no-store');
}
---

7. SEO et métadonnées

7.1. Balises meta

Balise	Source	Fallback
<title>	data.seo.metaTitle	data.title
<meta name="description">	data.seo.metaDescription	data.excerpt
<meta property="og:title">	data.seo.metaTitle	data.title
<meta property="og:description">	data.seo.metaDescription	data.excerpt
<meta property="og:image">	data.seo.ogImage	data.mainImage
<link rel="canonical">	URL publique de la page	-

7.2. Sitemap

• ✅ Cette route est-elle incluse dans le sitemap ? [Oui/Non]
• ✅ Fréquence de mise à jour : [daily / weekly / monthly]
• ✅ Priorité : [0.0 à 1.0]

7.3. Indexation Pagefind

• ✅ Cette route est-elle indexée par Pagefind ? [Oui/Non]
• ✅ Poids du titre : [2.0]
• ✅ Filtres applicables : [type, catégorie]

8. Composants UI utilisés

Composant	Fichier	Rôle	Hydratation
BaseLayout	src/layouts/BaseLayout.astro	Structure HTML	Aucune
HeroSection	src/components/sections/HeroSection.astro	Section hero	Aucune
MobileNav	src/components/ui/MobileNav.astro	Navigation mobile	client:load
[Autre]	[Chemin]	[Rôle]	[Stratégie]

9. Sécurité

9.1. Accès et authentification

Condition	Comportement
Accès public	Page accessible sans authentification
Mode Preview	Cookie sanity-preview requis pour voir les drafts
Endpoint API sensible	Validation du secret/token requise

9.2. Validation des entrées

• ✅ Les paramètres d’URL sont validés (format du slug)
• ✅ Les query strings sont sanitizées
• ✅ Les entrées de formulaire sont validées côté serveur
• ✅ Protection CSRF pour les endpoints POST

9.3. En-têtes de sécurité

Injectés par le Middleware Cloudflare (voir /cloudflare/workers/middleware.md) :

• Content-Security-Policy
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Strict-Transport-Security

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Page 404	Slug incorrect ou document non publié	Vérifier le slug dans Sanity
Contenu draft en production	Mode preview activé par erreur	Supprimer le cookie sanity-preview
Page blanche	Erreur GROQ ou type manquant	Vérifier les logs de build
Cache stale	CDN non invalidé	Attendre le TTL ou forcer un rebuild
500 en SSR	Token Sanity manquant	Vérifier les variables d’environnement
getStaticPaths lent	Requête GROQ non optimisée	Ajouter des projections explicites

10.2. Logs et monitoring

# Logs de développement
npm run dev

# Logs de build (SSG)
npm run build -- --verbose

# Logs Cloudflare (SSR production)
wrangler pages deployment tail

# Vérification des types
npx astro check

10.3. Tests manuels

# Test de la route en local
curl -I http://localhost:4321/[chemin]

# Test du mode preview
curl -I -b "sanity-preview=true" http://localhost:4321/[chemin]

# Test d'un endpoint API
curl -X POST http://localhost:4321/api/[endpoint] \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Test de la gestion 404
curl -I http://localhost:4321/[chemin-inexistant]
# Attendu : 404 ou redirect vers /404

11. Bonnes pratiques

11.1. Architecture

• ✅ Utiliser export const prerender = true par défaut (SSG)
• ✅ N’utiliser prerender = false que si nécessaire (preview, formulaires, API)
• ✅ Centraliser les requêtes GROQ dans src/lib/queries.ts
• ✅ Toujours typer les données avec les types générés par sanity-typegen
• ✅ Gérer le cas 404 explicitement

11.2. Performance

• ✅ Utiliser getStaticPaths pour pré-générer les pages dynamiques en SSG
• ✅ Limiter les projections GROQ aux champs nécessaires
• ✅ Utiliser loading="lazy" pour les images non-LCP
• ✅ Éviter les composants hydratés sauf si interaction requise

11.3. Maintenance

• ✅ Documenter les changements de route dans ce fichier
• ✅ Mettre à jour le sitemap lors de l’ajout/suppression de routes
• ✅ Tester les routes en staging avant production
• ✅ Vérifier les redirects lors de la modification de slugs

12. Évolutions et roadmap

12.1. Améliorations planifiées

• [Évolution 1 : ex. Pagination pour les listings]
• [Évolution 2 : ex. Support i18n (routes localisées)]
• [Évolution 3 : ex. View Transitions Astro]

12.2. Limitations connues

• ❌ Les pages SSG ne supportent pas le mode Preview
• ❌ getStaticPaths est exécuté uniquement au build (pas de mise à jour en temps réel)
• ❌ Les Pages Functions SSR ont une limite de 128 MB de mémoire

13. Ressources liées1/2

• Documentation Astro : Routing
• Documentation Astro : getStaticPaths
• Documentation Astro : Endpoints
• DAT L2 : §3 - Structure des Routes et Stratégie de Rendu
• DAT L2 : §5 - Intégration Sanity dans Astro
• DAT L3 : §3 - Middleware Global

13. Ressources liées2/2

• Routes associées :
  • [Liste des routes liées ou dépendantes]
• Fichiers concernés :
  • src/pages/[chemin].astro
  • src/lib/queries.ts
  • src/layouts/BaseLayout.astro

14. Historique des modifications1/2

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]
YYYY-MM-DD	1.1	[Modification]	[Nom]

14. Historique des modifications2/2

---

**Points clés de ce template :**
- Couvre les trois types de routes Astro (page SSG, page SSR, endpoint API)
- Détaille la stratégie de cache par mode de rendu
- Inclut la gestion du mode Preview au niveau de la route
- Documente le SEO, l'indexation Pagefind et le sitemap
- Fournit les variantes de code pour chaque type de route
- Inclut la gestion des erreurs et des codes HTTP
- Sépare clairement les paramètres d'URL, les query strings et la validation

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

[Nom de la Route]

1. 1. Vue d’ensemble2
2. 1.1. Description3
3. 1.2. Objectif4
4. 1.3. Caractéristiques5
5. 2. Architecture et flux6
6. 2.1. Diagramme de flux7
7. 2.2. Composants impliqués8
8. 3. Implémentation9
9. 3.1. Code de la route10
10. 3.2. Variante : Endpoint API (SSR)12
11. 3.3. Variante : Page SSR avec mode Preview13
12. 4. Données et requêtes GROQ14
13. 4.1. Requête principale15
14. 4.2. Requêtes secondaires (si applicable)16
15. 4.3. Types TypeScript associés17
16. 5. Paramètres et validation18
17. 5.1. Paramètres d’URL19
18. 5.2. Query strings (si applicable)20
19. 5.3. Gestion des erreurs21
20. 6. Stratégie de cache22
21. 6.1. En-têtes de cache23
22. 6.2. Implémentation dans la route24
23. 7. SEO et métadonnées25
24. 7.1. Balises meta26
25. 7.2. Sitemap27
26. 7.3. Indexation Pagefind28
27. 8. Composants UI utilisés29
28. 9. Sécurité30
29. 9.1. Accès et authentification31
30. 9.2. Validation des entrées32
31. 9.3. En-têtes de sécurité33
32. 10. Débogage et troubleshooting34
33. 10.1. Problèmes courants35
34. 10.2. Logs et monitoring36
35. 10.3. Tests manuels37
36. 11. Bonnes pratiques38
37. 11.1. Architecture39
38. 11.2. Performance40
39. 11.3. Maintenance41
40. 12. Évolutions et roadmap42
41. 12.1. Améliorations planifiées43
42. 12.2. Limitations connues44
43. 13. Ressources liées45
44. 14. Historique des modifications47