Configuration Astro Globale

Configuration Astro Globale

Documentation technique

Type de ressource : Configuration Framework Astro
Fichier source : apps/web/astro.config.mjs
Statut : Actif

1. Vue d’ensemble

1.1. Description

Configuration principale d’Astro pour le site web. Configure le mode de rendu SSR, l’adaptateur Cloudflare, et les intégrations (Sanity, Starlight, MDX, Sitemap, Tailwind).

1.2. Objectif

• Configurer le mode de rendu SSR (Server-Side Rendering) pour l’application
• Intégrer l’adaptateur Cloudflare pour le déploiement sur Cloudflare Workers
• Configurer les intégrations principales (Sanity CMS, Starlight, MDX, Sitemap)
• Configurer Tailwind CSS via Vite plugin

1.3. Périmètre concerné

• Mode de rendu : Hybrid (static par défaut, SSR à la demande via prerender = false)
• Adaptateur : Cloudflare
• Intégrations actives : Sanity, Starlight, MDX, Sitemap, Tailwind CSS
• Environnements : Development, Production

2. Configuration principale

2.1. Mode de sortie

astro.config.mjs

export default defineConfig({
  output: 'server', // Hybrid : static par défaut, SSR à la demande via prerender = false
  session: false,
});

Rationale : Le mode server avec l’adaptateur Cloudflare permet le rendu hybride : les pages sont pré-rendues en static par défaut (prerender = true), et le rendu dynamique (SSR) est activé à la demande via export const prerender = false sur les pages spécifiques. session: false indique que l’application n’utilise pas le système de sessions d’Astro.

2.2. Adaptateur Cloudflare1/2

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    imageService: 'passthrough',
    prerenderEnvironment: 'node',
  }),
});

2.2. Adaptateur Cloudflare2/2

Rationale : L’adaptateur Cloudflare est nécessaire pour déployer l’application SSR sur Cloudflare Workers. imageService: 'passthrough' indique que le service d’images est configuré séparément. prerenderEnvironment: 'node' permet le prerendering en environnement Node pendant le build.

2.3. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
SANITY_PROJECT_ID	ID du projet Sanity	✅	-
SANITY_DATASET	Nom du dataset	✅	-
SANITY_API_READ_TOKEN	Token de lecture (preview)	✅ (en preview)	-

3. Intégrations

3.1. Tailwind CSS1/2

import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [
      tailwindcss(),
    ],
  },
});

3.1. Tailwind CSS2/2

Configuration :

• Fichier : tailwind.config.mjs (à vérifier)
• Thème personnalisé : Non configuré (defaults Tailwind)
• Design tokens : Non configuré

3.2. Sanity CMS1/2

import sanity from '@sanity/astro';

export default defineConfig({
  integrations: [
    sanity({
      projectId: process.env.SANITY_PROJECT_ID,
      dataset: process.env.SANITY_DATASET,
    }),
  ],
});

3.2. Sanity CMS2/2

Rationale : L’intégration Sanity permet de connecter le frontend Astro au CMS Sanity. Le client Sanity sera reconfiguré dynamiquement dans src/lib/sanity.ts pour supporter le mode preview (useCdn: false, perspective: previewDrafts).

3.3. Starlight (Documentation)1/2

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Documentation',
      sidebar: [],
    }),
  ],
});

3.3. Starlight (Documentation)2/2

Configuration :

• Route interceptée : Non configurée (sidebar vide)
• Source de contenu : src/content/docs/ (à vérifier)
• Thème personnalisé : Non configuré

3.4. MDX

import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx(),
  ],
});

Rationale : L’intégration MDX permet d’utiliser le format MDX (Markdown + JSX) dans les fichiers de contenu.

3.5. Sitemap

import sitemap from '@astrojs/sitemap';

export default defineConfig({
  integrations: [
    sitemap(),
  ],
});

Rationale : L’intégration Sitemap génère automatiquement un sitemap.xml pour le SEO.

3.6. Autres intégrations

Intégration	Rôle	Configuration
Pagefind	Recherche (non configuré)	Non intégré
React	Composants React (non configuré)	Non intégré

4. Build et déploiement

4.1. Commandes npm

// package.json (apps/web/package.json)
{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

4.2. Pipeline CI/CD

Non documenté - le déploiement est automatique via GitHub Actions (selon règles globales).

4.3. Variables d’environnement CI/CD

Variable	Description	Obligatoire
SANITY_PROJECT_ID	ID du projet Sanity	✅
SANITY_DATASET	Nom du dataset	✅
SANITY_API_READ_TOKEN	Token de lecture	✅

5. Configuration du mode Preview

5.1. Détection du mode Preview

src/lib/sanity.ts

export function getSanityClient(isPreview: boolean = false) {
  return createClient({
    projectId,
    dataset,
    apiVersion: '2026-09-06',
    useCdn: !isPreview,
    perspective: isPreview ? 'previewDrafts' : 'published',
    token: isPreview ? readToken : undefined,
  });
}

5.2. Règles importantes

• ✅ Le mode Preview utilise useCdn: false et perspective: 'previewDrafts'
• ✅ Le token SANITY_API_READ_TOKEN est uniquement disponible en runtime
• ✅ La documentation Starlight n’est pas concernée par ce mécanisme
• ✅ Les routes /api/preview et /api/exit-preview gèrent le cookie de preview

6. Stratégie de cache

6.1. Politique de cache par type de page

Non documenté - la stratégie de cache n’est pas explicitement configurée dans l’implémentation actuelle.

6.2. Configuration dans les pages SSR

Non implémenté - les headers Cache-Control ne sont pas explicitement configurés dans les pages.

7. Typage et génération de types

7.1. Sanity TypeGen1/2

Implémenté pour le Studio - sanity-typegen est configuré dans apps/studio/sanity.cli.ts pour générer automatiquement les types TypeScript depuis les schémas Sanity.

7.1. Sanity TypeGen2/2

Configuration :

• Schema extraction : activé via schemaExtraction.enabled: true
• Typegen : activé via typegen.enabled: true
• Fichier de schéma généré : apps/studio/schema.json
• Fichier de types généré : apps/studio/sanity.types.ts

Note : Sanity TypeGen est configuré pour le Studio, pas pour le web app. Le web app n’utilise pas directement les types générés.

7.2. Commandes de génération

# Génération du schéma Sanity
cd apps/studio
npx sanity schema extract

# Génération des types Sanity
cd apps/studio
npx sanity typegen generate

7.3. Intégration CI/CD

À implémenter - la génération du schéma et des types doit être intégrée dans le pipeline CI/CD du Studio avant le build.

8. Performance et optimisation

8.1. Architecture en îlots

Non documenté - aucune stratégie d’hydratation d’îlots n’est explicitement configurée.

8.2. Optimisation des images

• ✅ L’adaptateur Cloudflare utilise imageService: 'passthrough'
• ✅ Cloudflare Images peut optimiser les images automatiquement

8.3. Core Web Vitals

Non documenté - aucun objectif spécifique de Core Web Vitals n’est configuré.

9. Sécurité

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

Non documenté - les en-têtes de sécurité ne sont pas explicitement configurés dans cette configuration.

9.2. Tokens et secrets

• ✅ Les variables d’environnement sont chargées depuis .env à la racine du monorepo
• ✅ Les secrets ne sont pas exposés dans le code
• ✅ Le token Sanity est utilisé uniquement en mode preview

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Build échoue	Sanity API inaccessible	Vérifier les variables d’environnement
Preview ne fonctionne pas	Cookie non détecté	Vérifier les routes /api/preview et /api/exit-preview
Images non optimisées	imageService: ‘passthrough’	Configurer le service d’images Cloudflare
Starlight vide	Sidebar non configurée	Configurer la sidebar dans starlight

10.2. Logs et monitoring

# Logs de build
npm run build

# Logs de développement
npm run dev

# Logs Cloudflare (production)
wrangler tail

10.3. Tests manuels

# Test local
npm run dev

# Test de build
npm run build
npm run preview

# Vérification des types
npx astro check

11. Bonnes pratiques

11.1. Configuration

• ✅ Utiliser le mode server pour le SSR
• ✅ Configurer l’adaptateur Cloudflare pour l’alignement L3
• ✅ Centraliser la configuration du client Sanity dans src/lib/sanity.ts
• ✅ Documenter les changements de configuration dans ce fichier

11.2. Développement

• ✅ Charger les variables d’environnement depuis .env à la racine
• ✅ Utiliser dotenv pour le développement local
• ✅ Valider les types TypeScript avant chaque commit
• ✅ Vérifier les Core Web Vitals avec Lighthouse

11.3. Déploiement

• ✅ Utiliser GitHub Actions pour le déploiement automatique
• ✅ Vérifier les variables d’environnement dans l’hébergeur
• ✅ Tester le mode Preview en staging avant production
• ✅ Surveiller les erreurs 5xx après déploiement

12. Évolutions et roadmap

12.1. Améliorations planifiées

• Configuration de la stratégie de cache par type de page
• Configuration des en-têtes de sécurité
• Configuration de Starlight avec sidebar
• Intégration CI/CD pour la génération du schéma et des types Sanity

12.2. Limitations connues

• ❌ La stratégie de cache n’est pas explicitement configurée
• ❌ Starlight n’est pas configuré (sidebar vide)
• ❌ L’intégration CI/CD pour sanity-typegen n’est pas encore configurée

13. Ressources liées1/2

• Documentation Astro : Configuration Reference
• Documentation @astrojs/cloudflare : Cloudflare Adapter
• Documentation @sanity/astro : Sanity Integration
• Documentation @astrojs/starlight : Starlight Integration

13. Ressources liées2/2

• Fichiers concernés :
  • apps/web/astro.config.mjs
  • apps/web/package.json
  • apps/web/src/lib/sanity.ts
  • .env (racine du monorepo)

14. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale	Devin

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

Configuration Astro Globale

1. 1. Vue d’ensemble2
2. 1.1. Description3
3. 1.2. Objectif4
4. 1.3. Périmètre concerné5
5. 2. Configuration principale6
6. 2.1. Mode de sortie7
7. 2.2. Adaptateur Cloudflare8
8. 2.3. Variables d’environnement10
9. 3. Intégrations11
10. 3.1. Tailwind CSS12
11. 3.2. Sanity CMS14
12. 3.3. Starlight (Documentation)16
13. 3.4. MDX18
14. 3.5. Sitemap19
15. 3.6. Autres intégrations20
16. 4. Build et déploiement21
17. 4.1. Commandes npm22
18. 4.2. Pipeline CI/CD23
19. 4.3. Variables d’environnement CI/CD24
20. 5. Configuration du mode Preview25
21. 5.1. Détection du mode Preview26
22. 5.2. Règles importantes27
23. 6. Stratégie de cache28
24. 6.1. Politique de cache par type de page29
25. 6.2. Configuration dans les pages SSR30
26. 7. Typage et génération de types31
27. 7.1. Sanity TypeGen32
28. 7.2. Commandes de génération34
29. 7.3. Intégration CI/CD35
30. 8. Performance et optimisation36
31. 8.1. Architecture en îlots37
32. 8.2. Optimisation des images38
33. 8.3. Core Web Vitals39
34. 9. Sécurité40
35. 9.1. En-têtes de sécurité41
36. 9.2. Tokens et secrets42
37. 10. Débogage et troubleshooting43
38. 10.1. Problèmes courants44
39. 10.2. Logs et monitoring45
40. 10.3. Tests manuels46
41. 11. Bonnes pratiques47
42. 11.1. Configuration48
43. 11.2. Développement49
44. 11.3. Déploiement50
45. 12. Évolutions et roadmap51
46. 12.1. Améliorations planifiées52
47. 12.2. Limitations connues53
48. 13. Ressources liées54
49. 14. Historique des modifications56