Spécification : Sanity Visual Editing

Spécification : Sanity Visual Editing

Documentation technique

Slice : Slice 1 (Page d’accueil)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : SPEC

1. Objectif

Implémenter le Sanity Visual Editing (Presentation Tool + Stega) pour permettre aux collaborateurs de prévisualiser et modifier le contenu directement depuis le Studio, fonctionnant pour tous les types de pages (SSG et SSR).

2. Configuration technique

2.1. Configuration Sanity Studio

Fichier : apps/studio/sanity.config.ts

Plugin presentation tool :

import { presentationTool } from 'sanity/presentation'
import { defineLocations } from 'sanity/presentation'

export const resolve = {
  locations: {
    page: defineLocations({
      select: { title: 'title', slug: 'slug.current' },
      resolve: (doc) => ({
        locations: [
          { title: doc?.title || 'Untitled', href: doc?.slug?.current === '/' ? '/' : `/${doc?.slug?.current}` },
        ],
      }),
    }),
  },
}

export default defineConfig({
  plugins: [
    presentationTool({
      resolve,
      previewUrl: {
        initial: process.env.SANITY_STUDIO_PREVIEW_URL || 'http://localhost:4321',
        previewMode: {
          enable: '/api/draft-mode/enable',
        },
      },
    }),
  ],
})

2.2. Configuration Astro1/2

Fichier : apps/web/astro.config.mjs

Activation Stega :

import sanity from '@sanity/astro'

export default defineConfig({
  integrations: [
    sanity({
      projectId: process.env.SANITY_PROJECT_ID,
      dataset: process.env.SANITY_DATASET,
      useCdn: false,
      stega: {
        studioUrl: process.env.SANITY_STUDIO_PREVIEW_URL || 'http://localhost:3333',
      },
    }),
  ],
})

2.2. Configuration Astro2/2

Fichier : apps/web/src/layouts/MainLayout.astro

Rendu Visual Editing Overlay :

---
import { VisualEditing } from '@sanity/astro/visual-editing';
const visualEditingEnabled = !!Astro.cookies.get('sanity-perspective')?.value;
---
<VisualEditing enabled={visualEditingEnabled} />

2.3. Gestion des variables d’environnement

Variables nécessaires :

• SANITY_PROJECT_ID : Déjà configurée
• SANITY_DATASET : Déjà configurée
• SANITY_STUDIO_PREVIEW_URL : À ajouter (http://localhost:4321 en dev, URL prod en prod)
• SANITY_API_READ_TOKEN : Pour la perspective previewDrafts

3. Structure des fichiers

3.1. Fichier resolve

Fichier : apps/studio/sanity/presentation/resolve.ts

Structure :

import { defineLocations, PresentationPluginOptions } from 'sanity/presentation'

export const resolve: PresentationPluginOptions['resolve'] = {
  locations: {
    page: defineLocations({
      select: { title: 'title', slug: 'slug.current' },
      resolve: (doc) => ({
        locations: [
          { title: doc?.title || 'Untitled', href: doc?.slug?.current === '/' ? '/' : `/${doc?.slug?.current}` },
        ],
      }),
    }),
  },
}

3.2. Nettoyage Stega

Fichier : apps/web/src/lib/stega.ts

Structure :

import { stegaClean } from '@sanity/client/stega'

export function cleanStega<T>(value: T): T {
  if (typeof value === 'string') {
    return stegaClean(value) as T
  }
  return value
}

4. Implémentation

4.1. Configuration Studio

Modifications :

• Ajouter le plugin presentationTool
• Créer le fichier sanity/presentation/resolve.ts
• Configurer l’URL de preview selon l’environnement

4.2. Configuration Astro

Modifications :

• Activer stega: true dans l’intégration Sanity
• Vérifier que le client Sanity est configuré correctement

4.3. Utilisation des données

Composants :

• Les champs texte contiennent des métadonnées Stega
• Utiliser stegaClean pour les comparaisons et logiques
• Ne pas nettoyer pour le rendu (nécessaire pour click-to-edit)

5. Comportement attendu

5.1. Mode Development

Comportement :

• Studio accessible sur http://localhost:3333
• Presentation tool rendu avec http://localhost:4321
• Click-to-edit fonctionnel
• Mises à jour en temps réel

5.2. Mode Production

Comportement :

• Studio avec URL de production
• Presentation tool rendu avec URL de production
• Stega activé en production
• Cache CDN activé

5.3. Pages SSG (index.astro)

Comportement :

• Présentation tool fonctionne sur les pages prerendered
• Stega encodé dans le HTML statique
• Click-to-edit via metadata Stega

5.4. Pages SSR ([slug].astro)

Comportement :

• Présentation tool fonctionne sur les pages SSR
• Stega encodé dans le HTML généré
• Click-to-edit via metadata Stega

6. Tests et validation

6.1. Tests de configuration

Commandes :

task dev:studio
task dev

Attendu :

• Studio démarré avec plugin presentation tool
• Bouton “Presentation” visible dans le Studio
• Presentation tool rendu correctement

6.2. Tests de visual editing

Scénarios :

1. Ouvrir le Studio
2. Cliquer sur “Presentation”
3. Naviguer vers la page d’accueil
4. Modifier un champ dans le Studio
5. Vérifier la mise à jour en temps réel dans la Presentation tool
6. Tester le click-to-edit sur les éléments

6.3. Tests Stega

Commandes :

task build:web

Attendu :

• Build réussi
• HTML contient les métadonnées Stega
• Pas d’erreurs liées à Stega

7. Intégration avec l’existant

7.1. Compatibilité avec index.astro

État actuel :

• index.astro est prerendered (export const prerender = true)
• Utilise getSanityClient() existant
• Rendu PageBuilder

Modification requise :

• Aucune modification logique
• Stega activé via configuration Astro
• Presentation tool fonctionnera sur la page prerendered

7.2. Compatibilité avec [slug].astro

État actuel :

• [slug].astro est SSR (export const prerender = false)
• Utilise getSanityClient() existant
• Rendu PageBuilder

Modification requise :

• Aucune modification logique
• Stega activé via configuration Astro
• Presentation tool fonctionnera

7.3. Compatibilité avec welcome.astro

État actuel :

• welcome.astro est SSR
• Utilise getSanityClient() avec mode preview

Modification requise :

• Retirer la logique preview existante (bannière, cookie)
• Stega remplacera cette logique
• Présentation tool utilisé à la place

8. Nettoyage de l’approche précédente

8.1. Middleware Astro à supprimer

Fichier : apps/web/src/middleware.ts

• Déjà supprimé

8.2. Middleware Cloudflare à conserver

Fichier : services/preview-middleware/src/index.ts

• Garder pour l’API /api/preview utilisée par Studio
• Garder pour l’API /api/exit-preview
• Ce middleware reste nécessaire pour le lien Studio → Site

8.3. Bannières preview à supprimer

Fichiers :

• Retirer toute logique de bannière preview des composants
• Stega + Presentation tool remplacent cette approche

9. Problèmes potentiels et solutions

9.1. Presentation tool non visible

Problème : Plugin presentation tool non configuré

Solution :

• Vérifier sanity.config.ts
• Vérifier que le plugin est importé et configuré

9.2. Stega non fonctionnel

Problème : stega: true non activé

Solution :

• Vérifier astro.config.mjs
• Vérifier que stega: true est activé

9.3. Live Content API non fonctionnel

Problème : Mises à jour en temps réel ne fonctionnent pas

Solution :

• Vérifier que le client Sanity est configuré pour Live Content API
• Vérifier les variables d’environnement

10. Checklist de validation

Avant de passer à l’étape CODE :

• Documentation Studio visual editing complète
• Spécification technique complète
• Compatibilité avec l’existant analysée
• Nettoyage de l’approche précédente planifié
• Tests définis
• Problèmes potentiels identifiés

11. Approbation

Validation requise : Confirmer que la spécification peut passer à l’étape CODE.

12. Historique des modifications

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

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

Spécification : Sanity Visual Editing

1. 1. Objectif3
2. 2. Configuration technique4
3. 2.1. Configuration Sanity Studio5
4. 2.2. Configuration Astro6
5. 2.3. Gestion des variables d’environnement8
6. 3. Structure des fichiers9
7. 3.1. Fichier resolve10
8. 3.2. Nettoyage Stega11
9. 4. Implémentation12
10. 4.1. Configuration Studio13
11. 4.2. Configuration Astro14
12. 4.3. Utilisation des données15
13. 5. Comportement attendu16
14. 5.1. Mode Development17
15. 5.2. Mode Production18
16. 5.3. Pages SSG (index.astro)19
17. 5.4. Pages SSR ([slug].astro)20
18. 6. Tests et validation21
19. 6.1. Tests de configuration22
20. 6.2. Tests de visual editing23
21. 6.3. Tests Stega24
22. 7. Intégration avec l’existant25
23. 7.1. Compatibilité avec index.astro26
24. 7.2. Compatibilité avec [slug].astro27
25. 7.3. Compatibilité avec welcome.astro28
26. 8. Nettoyage de l’approche précédente29
27. 8.1. Middleware Astro à supprimer30
28. 8.2. Middleware Cloudflare à conserver31
29. 8.3. Bannières preview à supprimer32
30. 9. Problèmes potentiels et solutions33
31. 9.1. Presentation tool non visible34
32. 9.2. Stega non fonctionnel35
33. 9.3. Live Content API non fonctionnel36
34. 10. Checklist de validation37
35. 11. Approbation38
36. 12. Historique des modifications39