Configuration Astro Globale

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 Cloudflare

import cloudflare from '@astrojs/cloudflare';

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

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 CSS

import tailwindcss from '@tailwindcss/vite';

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

Configuration :

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

3.2. Sanity CMS

import sanity from '@sanity/astro';

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

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)

import starlight from '@astrojs/starlight';

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

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 TypeGen

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.

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ées

• Documentation Astro : Configuration Reference
• Documentation @astrojs/cloudflare : Cloudflare Adapter
• Documentation @sanity/astro : Sanity Integration
• Documentation @astrojs/starlight : Starlight Integration
• 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