Configuration Astro Globale

Type de ressource : Configuration Framework Astro
Fichier source : astro.config.mjs
Statut : [Actif / Déprécié / En développement]

1. Vue d’ensemble

1.1. Description

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

1.2. Objectif

• [Objectif principal : ex. configurer le mode hybride SSG/SSR]
• [Bénéfice pour l’architecture : ex. alignement avec Cloudflare Pages Functions]

1.3. Périmètre concerné

• Mode de rendu : [Hybrid / Static / Server]
• Adaptateur : [Cloudflare / Vercel / Netlify / Node]
• Intégrations actives : [Liste : Tailwind, Sanity, Starlight, Pagefind, etc.]
• Environnements : [Development / Staging / Production]

2. Configuration principale

2.1. Mode de sortie

astro.config.mjs

export default defineConfig({
  output: 'hybrid', // SSG par défaut, SSR explicite
});

Rationale : [Expliquer pourquoi ce mode est choisi]

2.2. Adaptateur Cloudflare

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    platformProxy: {
      enabled: true, // Facilite le développement local avec Wrangler
    },
  }),
});

Rationale : [Expliquer pourquoi cet adaptateur est nécessaire]

2.3. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
PUBLIC_SANITY_PROJECT_ID	ID du projet Sanity	✅	-
PUBLIC_SANITY_DATASET	Nom du dataset	✅	production
SANITY_API_READ_TOKEN	Token de lecture (preview)	✅ (en preview)	-
[Autre variable]	[Description]	[✅/❌]	[Valeur]

3. Intégrations

3.1. Tailwind CSS

import tailwind from '@astrojs/tailwind';

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

Configuration :

• Fichier : tailwind.config.mjs
• Thème personnalisé : [Oui/Non]
• Design tokens : [Lien vers tokens.css]

3.2. Sanity CMS

import sanity from '@sanity/astro';

export default defineConfig({
  integrations: [
    sanity({
      projectId: 'votre_project_id',
      dataset: 'production',
      useCdn: true, // CDN Sanity pour le build SSG
      // Le client sera reconfiguré dynamiquement en mode preview
    }),
  ],
});

Rationale : [Expliquer la configuration du CDN et le mode preview]

3.3. Starlight (Documentation)

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Documentation Technique',
      sidebar: [
        { label: 'Guide de Démarrage', autogenerate: { directory: 'guide' } },
        { label: 'Références API', autogenerate: { directory: 'api' } },
      ],
    }),
  ],
});

Configuration :

• Route interceptée : /docs
• Source de contenu : src/content/docs/
• Thème personnalisé : [Lien vers starlight-overrides.css]

3.4. Pagefind (Recherche)

import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [
    pagefind({
      ranking: {
        pageLength: 0.1,
        termFrequency: 0.5,
        termSaturation: 0.5,
        termSimilarity: 0.9,
      },
    }),
  ],
});

Rationale : [Expliquer pourquoi Pagefind est utilisé et comment il s’intègre]

3.5. Sitemap

import sitemap from '@astrojs/sitemap';

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

3.6. Autres intégrations

Intégration	Rôle	Configuration
[Nom]	[Rôle]	[Lien ou extrait]

4. Build et déploiement

4.1. Commandes npm

package.json

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "typegen": "sanity typegen generate"
  }
}

4.2. Pipeline CI/CD

# Exemple de workflow GitHub Actions
name: Build and Deploy
on:
  push:
    branches: [main]
  repository_dispatch:
    types: [sanity-webhook]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run typegen
      - run: npm run build
      - run: npm run deploy

4.3. Variables d’environnement CI/CD

Variable	Description	Obligatoire
PUBLIC_SANITY_PROJECT_ID	ID du projet Sanity	✅
PUBLIC_SANITY_DATASET	Nom du dataset	✅
SANITY_API_READ_TOKEN	Token de lecture	✅
[Autre variable]	[Description]	[✅/❌]

5. Configuration du mode Preview

5.1. Détection du mode Preview

src/lib/sanity.ts

import { createClient } from '@sanity/client';
import type { AstroGlobal } from 'astro';

export function getSanityClient(astro: AstroGlobal) {
  const isPreview =
    astro.cookies.get('sanity-preview')?.value === 'true' ||
    astro.request.headers.get('x-sanity-preview') === 'true';

  return createClient({
    projectId: import.meta.env.PUBLIC_SANITY_PROJECT_ID,
    dataset: import.meta.env.PUBLIC_SANITY_DATASET,
    apiVersion: '2025-01-01',
    useCdn: !isPreview,
    perspective: isPreview ? 'previewDrafts' : 'published',
    token: isPreview
      ? import.meta.env.SANITY_API_READ_TOKEN
      : undefined,
  });
}

5.2. Règles importantes

• ✅ Aucune page en mode Preview n’est générée en SSG
• ✅ Le token SANITY_API_READ_TOKEN est uniquement disponible en runtime
• ✅ La documentation Starlight n’est pas concernée par ce mécanisme
• ✅ Le Middleware Cloudflare gère la validation du secret et la pose du cookie

6. Stratégie de cache

6.1. Politique de cache par type de page

Type de page	Cache-Control (navigateur)	CDN-Cache-Control (Cloudflare)
Pages SSG	public, max-age=31536000, immutable	public, max-age=31536000, immutable
Pages SSR semi-dynamiques	public, max-age=60	max-age=300, stale-while-revalidate=86400
Pages SSR hautement dynamiques	private, no-store	no-store
Pages de formulaire (GET)	public, max-age=300	max-age=600, stale-while-revalidate=3600
Réponses d’actions (POST)	no-store	no-store
Mode Preview	no-store, no-cache, must-revalidate, private	no-store

6.2. Configuration dans les pages SSR

// Exemple dans une page SSR
Astro.response.headers.set('Cache-Control', 'public, max-age=60');
Astro.response.headers.set('CDN-Cache-Control', 'max-age=300, stale-while-revalidate=86400');

7. Typage et génération de types

7.1. Sanity TypeGen

sanity-typegen.config.json

{
  "path": "./src/**/*.{ts,tsx,astro}",
  "schema": "./schema.json",
  "generates": "./src/types/sanity.d.ts"
}

7.2. Commandes de génération

# Générer le schéma depuis Sanity
npx sanity schema extract --enforce-required-fields

# Générer les types TypeScript
npx sanity typegen generate

7.3. Intégration CI/CD

# Dans le pipeline CI
- run: npm run typegen
- run: npm run build

Règle : Le pipeline CI échoue si les types générés ne sont pas à jour par rapport aux schémas.

8. Performance et optimisation

8.1. Architecture en îlots

Composant	Stratégie d’hydratation	Rationale
Navigation mobile	client:load	Critique pour l’UX
Carrousel témoignages	client:visible	Chargement différé
Formulaire de contact	client:load	Interaction immédiate
Contenu statique	Aucune	HTML pur

8.2. Optimisation des images

• ✅ Toujours fournir width, height et alt
• ✅ Utiliser loading="lazy" sauf pour les images LCP
• ✅ Générer des srcset / sizes pour le responsive
• ✅ Formats modernes : WebP/AVIF (via Cloudflare)

8.3. Core Web Vitals

Métrique	Objectif	Stratégie
LCP	< 2.5s	Images optimisées, fonts préchargées
INP	< 200ms	JavaScript minimal, îlots ciblés
CLS	< 0.1	Dimensions explicites, fonts stables

9. Sécurité

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

Les en-têtes de sécurité sont injectés par le Middleware Cloudflare (voir DAT L3 §3.2) :

En-tête	Valeur	Rationale
X-Content-Type-Options	nosniff	Évite le MIME sniffing
X-Frame-Options	DENY	Protection clickjacking
Referrer-Policy	strict-origin-when-cross-origin	Contrôle du referrer
Strict-Transport-Security	max-age=31536000; includeSubDomains; preload	Force HTTPS
Content-Security-Policy	[Voir DAT L3 §3.2]	Protection XSS

9.2. Tokens et secrets

• ✅ Les tokens publics (PUBLIC_*) peuvent être exposés côté client
• ✅ Les tokens privés (SANITY_API_*) ne doivent jamais être exposés côté client
• ✅ Les secrets sont injectés via wrangler secret put

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Build échoue	Types Sanity obsolètes	Exécuter npm run typegen
Preview ne fonctionne pas	Cookie non détecté	Vérifier le Middleware Cloudflare
Pages SSR lentes	Cache mal configuré	Vérifier les headers Cache-Control
Images non optimisées	Cloudflare Polish désactivé	Activer Polish dans le Dashboard
Erreur 500 en production	Token Sanity manquant	Vérifier les variables d’environnement

10.2. Logs et monitoring

# Logs de build
npm run build -- --verbose

# Logs de développement
npm run dev

# Logs Cloudflare (production)
# Dashboard Cloudflare → Analytics & Logs

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 hybrid pour bénéficier du SSG par défaut
• ✅ Toujours spécifier 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

• ✅ Tester en local avec platformProxy.enabled: true
• ✅ Utiliser les variables d’environnement pour tous les secrets
• ✅ Valider les types TypeScript avant chaque commit
• ✅ Vérifier les Core Web Vitals avec Lighthouse

11.3. Déploiement

• ✅ Exécuter npm run typegen avant le build
• ✅ 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

• [Évolution 1 : ex. Ajout de l’intégration i18n]
• [Évolution 2 : ex. Migration vers Astro 5.x]
• [Évolution 3 : ex. Implémentation de View Transitions]

12.2. Limitations connues

• ❌ Le mode Preview ne fonctionne pas avec le SSG (SSR uniquement)
• ❌ Les Pages Functions ont des limites de mémoire (128 MB)
• ❌ Le build peut être lent avec beaucoup de pages (> 1000)

13. Ressources liées

• Documentation Astro : Configuration Reference
• Documentation @astrojs/cloudflare : Cloudflare Adapter
• DAT L2 : §2 - Architecture de Rendu & Configuration du Framework
• DAT L3 : §3 - Middleware Global (En-têtes de sécurité)
• Fichiers concernés :
  • astro.config.mjs
  • package.json
  • src/lib/sanity.ts
  • tailwind.config.mjs
  • sanity-typegen.config.json

14. Historique des modifications

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

---

**Points clés de ce template :**
- Documente la configuration globale d'Astro (mode hybride, adaptateur, intégrations)
- Détaille la stratégie de cache par type de page
- Inclut la configuration du mode Preview et la génération de types
- Fournit les bonnes pratiques de performance et de sécurité
- Sépare clairement la configuration, le build, et le déploiement
- Inclut un guide de débogage complet