Sanity API Configuration

Type de ressource : Configuration API Sanity (Client / Token / Requête)
Fichier source : apps/web/src/lib/sanity.ts
Statut : Actif

1. Vue d’ensemble

1.1. Description

Configuration du client Sanity pour la communication avec l’API Sanity. Supporte le mode published (CDN) et previewDrafts (sans CDN) pour la prévisualisation des documents non publiés.

1.2. Objectif

• Interface centralisée pour les requêtes Sanity
• Support du mode preview pour les drafts
• Configuration des credentials et du dataset
• Gestion automatique du token pour l’accès aux drafts

1.3. Périmètre concerné

• Environnements : Development, Production
• Couches utilisatrices : L2 (Astro)
• Types de requêtes : CDN (published), Preview (previewDrafts)

2. Architecture et flux

2.1. Diagramme de flux

[Astro]
     │
     ▼
[Client Sanity (configuré)]
     │  • Détection du mode preview
     │  • Sélection du token approprié
     │  • Configuration du CDN
     ▼
[Sanity Content Lake API]
     │  • Requête GROQ
     │  • Validation des permissions
     ▼
[Réponse JSON typée]

2.2. Composants impliqués

Composant	Rôle	Couche
getSanityClient()	Factory de client Sanity avec détection de mode	L2 (Astro)
createClient()	Client Sanity de base (@sanity/client)	L2
getAmn()	Fonction utilitaire pour récupérer le document AMN	L2 (Astro)
Variables d’environnement	Configuration des tokens et IDs	Runtime

3. Configuration

3.1. Variables d’environnement requises

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

3.2. Configuration du client (L2 - Astro)

apps/web/src/lib/sanity.ts

import { createClient } from '@sanity/client'

const projectId = import.meta.env.SANITY_PROJECT_ID || process.env.SANITY_PROJECT_ID || ''
const dataset = import.meta.env.SANITY_DATASET || process.env.SANITY_DATASET || 'development'
const readToken = import.meta.env.SANITY_API_READ_TOKEN || process.env.SANITY_API_READ_TOKEN

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

export const client = getSanityClient(false)

3.3. Configuration du client (L3 - Workers)

Non implémenté dans ce fichier - les Workers utilisent leur propre configuration.

4. Typage et génération automatique

4.1. Configuration de sanity-typegen

Non implémenté - sanity-typegen n’est pas configuré dans le projet actuel.

4.2. Commandes de génération

Non applicable - sanity-typegen n’est pas utilisé.

4.3. Types générés (exemple)

Types non générés automatiquement - définitions manuelles à implémenter si nécessaire.

5. Requêtes GROQ

5.1. Requête typée (exemple)

apps/web/src/lib/sanity.ts

export async function getAmn(isPreview: boolean = false) {
  try {
    const sanityClient = getSanityClient(isPreview)
    const query = `*[_type == "amn" && status == "active"][0]`
    return await sanityClient.fetch(query)
  } catch (error) {
    console.error('Error fetching AMN document from Sanity:', error)
    return null
  }
}

5.2. Bonnes pratiques GROQ

• ✅ Toujours typer les résultats avec client.fetch<T>() (à implémenter)
• ✅ Utiliser des projections explicites (éviter * non filtré)
• ✅ Filtrer par status == "active" pour le schéma AMN
• ✅ Utiliser order() pour trier les résultats
• ✅ Gérer les erreurs avec try/catch

6. Sécurité

6.1. Gestion des tokens

Token	Permissions	Stockage	Exposition
SANITY_PROJECT_ID	Lecture publique	.env	Côté client ✅
SANITY_DATASET	Lecture publique	.env	Côté client ✅
SANITY_API_READ_TOKEN	Lecture des drafts	.env (non versionné)	Runtime uniquement ❌

6.2. Règles de sécurité

• ✅ Les tokens publics peuvent être exposés côté client
• ✅ Le token de lecture n’est transmis qu’en mode preview
• ✅ Utiliser des tokens avec les permissions minimales nécessaires
• ✅ Rotation régulière des tokens (tous les 90 jours recommandé)

6.3. Permissions Sanity

Configuration dans Sanity Studio :

• Settings → API → Tokens
• Créer des tokens avec des scopes spécifiques :
  • read : Lecture uniquement

7. Performance

7.1. Stratégie de cache

Mode	useCdn	Rationale
Production (published)	true	Contenu mis en cache par Sanity CDN
Preview (previewDrafts)	false	Contenu draft non caché

7.2. Optimisation des requêtes

• ✅ Utiliser des projections pour réduire la taille des réponses
• ✅ Filtrer côté serveur plutôt que côté client
• ✅ Activer le CDN en mode published
• ✅ Sélectionner uniquement les champs requis

7.3. Limites et quotas

Limite	Valeur	Rationale
Taille max requête	16 KB	Limite Sanity API
Taille max réponse	100 MB	Limite Sanity API
Requêtes par seconde	100 (Free) / 1000 (Pro)	Quota Sanity
Temps de réponse	< 5s recommandé	UX optimale

8. Débogage et troubleshooting

8.1. Problèmes courants

Symptôme	Cause probable	Solution
Erreur 401 Unauthorized	Token manquant ou invalide	Vérifier SANITY_API_READ_TOKEN
Drafts non visibles	Perspective incorrecte	Vérifier isPreview parameter
Données obsolètes	CDN activé en mode preview	Vérifier useCdn: false
Erreur de connexion	Project ID ou dataset incorrect	Vérifier variables d’environnement

8.2. Logs et monitoring

// Logs à vérifier en cas de problème
console.error('Error fetching AMN document from Sanity:', error)

// Vérifier les requêtes dans l'onglet Network du navigateur
// Vérifier les logs Sanity Studio → Settings → API → Activity

8.3. Tests manuels

# Test de requête GROQ via curl
curl "https://[project-id].api.sanity.io/v2026-09-06/data/query/production?query=*[_type=='post'][0...5]" \
  -H "Authorization: Bearer [token]"

9. Bonnes pratiques

9.1. Architecture

• ✅ Centraliser la configuration du client dans apps/web/src/lib/sanity.ts
• ✅ Séparer les requêtes GROQ récurrentes dans des fonctions utilitaires
• ✅ Toujours typer les résultats (à implémenter avec sanity-typegen)
• ✅ Utiliser des factory functions pour créer les clients (flexibilité)

9.2. Code

• ✅ Utiliser async/await pour les requêtes
• ✅ Gérer les erreurs avec try/catch
• ✅ Logger les erreurs de requête pour le debugging
• ✅ Ne jamais hardcoder les IDs de projet ou datasets

9.3. Environnements

• ✅ Utiliser des variables d’environnement différentes par environnement
• ✅ Tester en local avant déploiement
• ✅ Documenter les différences de configuration entre environnements

10. Évolutions et roadmap

10.1. Améliorations planifiées

• Intégration de sanity-typegen pour la génération de types
• Cache côté serveur avec invalidation intelligente
• Requêtes réutilisables centralisées
• Monitoring des performances des requêtes

10.2. Limitations connues

• ❌ Le mode preview nécessite un token avec permissions de lecture
• ❌ Les drafts ne sont pas accessibles via CDN
• ❌ La configuration actuelle ne supporte pas les mutations (écriture)

11. Ressources liées

• Documentation Sanity : API Reference
• Documentation Sanity : Preview Content
• Client Sanity : @sanity/client
• Pages Astro : apps/web/src/pages/api/preview.ts, apps/web/src/pages/api/exit-preview.ts
• Configuration : apps/web/astro.config.mjs

12. Historique des modifications

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