Modèles Sanity
Guide rapide : Utilisez Sanity pour la gestion de contenu structuré avec des requêtes GROQ, des schémas typés via
defineType/defineField, et@sanity/clientpour la récupération de données. Définissez toujoursapiVersionsur une chaîne datée, utilisezuseCdn: truepour les lectures publiques, gérez les documents brouillons explicitement, utilisez@sanity/image-urlpour les transformations d'images, et rendez le texte enrichi avec@portabletext/react. Générez les types TypeScript avecsanity typegen generate.
<critical_requirements>
CRITIQUE : Avant d'utiliser cette compétence
Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports,
import type, constantes nommées)
(Vous DEVEZ toujours définir apiVersion sur createClient avec une chaîne datée comme '2025-02-19' — son omission utilise une API héritée qui peut cesser de fonctionner)
(Vous DEVEZ utiliser useCdn: true pour les requêtes de lecture publiques et useCdn: false lorsque vous utilisez un jeton ou avez besoin de données fraîches)
(Vous DEVEZ utiliser des requêtes GROQ paramétrées ($param) pour toutes les valeurs dynamiques — n'interpolez jamais les entrées utilisateur dans les chaînes GROQ)
(Vous DEVEZ gérer les brouillons explicitement — les documents brouillons ont un _id préfixé par drafts. et ne sont pas retournés par défaut avec perspective: 'published')
(Vous DEVEZ utiliser defineQuery() de groq et assigner les requêtes à des variables nommées pour la génération de types TypeGen)
</critical_requirements>
Auto-détection : Sanity, sanity, @sanity/client, createClient, GROQ, groq, defineType, defineField, defineArrayMember, @sanity/image-url, urlFor, @portabletext/react, PortableText, portable text, block content, sanity.config, sanity.cli, typegen, sanity studio, content lake
Quand l'utiliser :
- Configurer
@sanity/clientaveccreateClientpour la récupération de données - Écrire des requêtes GROQ (filtres, projections, jointures, tris, découpage)
- Définir des schémas de contenu avec
defineType,defineField,defineArrayMember - Rendre du Portable Text (contenu de blocs) avec
@portabletext/react - Générer des URL d'images avec
@sanity/image-url(images responsives, recadrages, points chauds) - Effectuer des mutations (créer, patcher, supprimer, transactions)
- Configurer des écouteurs en temps réel avec
client.listen() - Générer des types TypeScript avec Sanity TypeGen
Modèles clés couverts :
- Configuration du client avec
createClientet configuration deapiVersion - Langage de requête GROQ : filtres, projections, tris, découpage, jointures, références
- Définitions de schémas : types de documents, types d'objets, tableaux, références, images
- Rendu de Portable Text avec des composants personnalisés
- Générateur d'URL d'images avec images responsives et transformations
- Mutations : créer, createOrReplace, patcher, supprimer, transactions
- Écouteurs en temps réel via
client.listen() - TypeGen pour des requêtes GROQ typées avec
defineQuery()
Quand NE PAS l'utiliser :
- API uniquement GraphQL (Sanity prend en charge principalement GROQ ; utilisez la compétence GraphQL si nécessaire)
- Accès direct à la base de données (Sanity est un lac de contenu hébergé, pas une base de données)
- Plateformes CMS non Sanity (utilisez la compétence dédiée à votre CMS)
Ressources détaillées :
- Pour les cadres de décision et les tableaux de référence rapide, voir reference.md
Client & GROQ :
- examples/core.md — Configuration du client, requêtes GROQ, gestion des erreurs, TypeGen
Schémas :
- examples/schemas.md — defineType, defineField, types de documents, types d'objets, références, images
Contenu riche :
- examples/rich-content.md — Rendu de Portable Text, générateur d'URL d'images, images responsives
Mutations & Temps réel :
- examples/mutations.md — Créer, patcher, supprimer, transactions, écouteurs en temps réel
Philosophie
Sanity est une plateforme de contenu structuré construite autour d'un lac de contenu en temps réel, de GROQ (Graph-Relational Object Queries) comme langage de requête, et de Sanity Studio comme environnement d'édition personnalisable.
Principes fondamentaux :
- Contenu structuré — Le contenu est défini par des schémas (
defineType,defineField) qui décrivent la forme, la validation et l'interface utilisateur éditoriale. Les schémas sont du code, pas des fichiers de configuration. - Requêtage GROQ d'abord — GROQ vous permet de filtrer, projeter, joindre et remodeler les données en une seule requête. Contrairement à REST ou GraphQL, les requêtes GROQ retournent exactement la forme que vous définissez dans la projection.
- Le contenu comme données — Le texte enrichi est stocké sous forme de Portable Text (une spécification basée sur JSON), ce qui le rend rendu dans n'importe quel framework frontend sans verrouillage propriétaire.
- Versionnage de l'API — Chaque client doit spécifier une chaîne de date
apiVersion. Cela épinglé votre code à un comportement d'API spécifique, empêchant les changements de dernière minute d'affecter la production. - Mise en cache CDN — Les requêtes de lecture publiques utilisent
useCdn: truepour des réponses mises en cache en périphérie. Les mutations et les lectures authentifiées utilisentuseCdn: falsepour des données fraîches. - Génération de types — Sanity TypeGen génère des types TypeScript à partir de vos schémas et de vos requêtes GROQ, permettant une sécurité de type de bout en bout, du modèle de contenu au frontend.
Quand utiliser Sanity :
- Sites web et applications axés sur le contenu (blogs, sites marketing, documentation)
- Projets nécessitant une édition collaborative en temps réel dans un studio personnalisable
- Diffusion de contenu multicanal (web, mobile, IoT) à partir d'une source de contenu unique
- Équipes souhaitant des requêtes de contenu sécurisées avec GROQ et TypeGen
Quand NE PAS utiliser :
- Données transactionnelles nécessitant des garanties ACID (utilisez une base de données)
- Contenu généré par l'utilisateur à grande échelle (Sanity est optimisé pour le contenu éditorial)
- Projets nécessitant un CMS auto-hébergé (le lac de contenu de Sanity est hébergé, bien que le Studio soit open source)
Modèles Fondamentaux
Modèle 1 : Configuration du Client avec createClient
Configurez @sanity/client avec l'ID du projet, le jeu de données, la version de l'API et la préférence CDN. Définissez toujours apiVersion sur une chaîne datée et useCdn explicitement.
import { createClient } from "@sanity/client";
export const client = createClient({
projectId: process.env.SANITY_PROJECT_ID!,
dataset: process.env.SANITY_DATASET!,
apiVersion: "2025-02-19", // Épinglé à une date de version d'API spécifique
useCdn: true, // true pour les lectures publiques, false pour les données authentifiées/fraîches
});
Pour une configuration double client (public + aperçu avec jeton), voir examples/core.md.
Modèle 2 : Requêtes GROQ avec Filtres et Projections
Les requêtes GROQ combinent filtres, projections, tris et découpage. Utilisez toujours defineQuery() pour TypeGen et $param pour les valeurs dynamiques.
import { defineQuery } from "groq";
const POST_BY_SLUG_QUERY = defineQuery(`
*[_type == "post" && slug.current == $slug][0]{
_id, title, body, "author": author->{name, image}
}
`);
const post = await client.fetch(POST_BY_SLUG_QUERY, { slug: "my-post" });
N'interpolez jamais les entrées utilisateur dans les chaînes GROQ — utilisez toujours les paramètres $param pour empêcher l'injection GROQ. Pour les requêtes avancées (requêtes combinées, projections conditionnelles), voir examples/core.md.
Modèle 3 : Définitions de Schémas avec defineType et defineField
Définissez la structure du contenu avec defineType, defineField et defineArrayMember de "sanity" pour la sécurité des types et l'interface utilisateur du Studio.
import { defineType, defineField } from "sanity";
export const postType = defineType({
name: "post",
type: "document",
fields: [
defineField({
name: "title",
type: "string",
validation: (r) => r.required(),
}),
defineField({ name: "slug", type: "slug", options: { source: "title" } }),
],
});
Pour les schémas complets (images avec hotspot, tableaux, références, aperçus, types d'objets), voir examples/schemas.md.
Modèle 4 : Rendu de Portable Text
Rendez le contenu des blocs avec @portabletext/react. Définissez des PortableTextComponents personnalisés pour les blocs non standard (images, code) et les marques (liens, surlignages).
import { PortableText } from "@portabletext/react";
<PortableText value={body} components={components} />;
N'utilisez pas le package obsolète @sanity/block-content-to-react. Pour des exemples complets de composants, voir examples/rich-content.md.
Modèle 5 : Générateur d'URL d'Images
Utilisez @sanity/image-url pour générer des URL d'images optimisées et responsives avec support du recadrage et des hotspots.
import { createImageUrlBuilder } from "@sanity/image-url";
const builder = createImageUrlBuilder(client);
export function urlFor(source: SanityImageSource) {
return builder.image(source);
}
// Utilisation : urlFor(image).width(800).auto("format").url()
Pour les modèles srcSet responsifs et les transformations d'images, voir examples/rich-content.md.
Modèle 6 : Mutations (Créer, Patcher, Supprimer)
Utilisez les méthodes @sanity/client pour les mutations de documents. Appelez toujours .commit() sur les correctifs et les transactions.
await client.create({ _type: "post", title: "Nouvel article" });
await client.patch("post-123").set({ title: "Mis à jour" }).commit();
await client.delete("post-123");
Pour createOrReplace, createIfNotExists, transactions, insertions dans des tableaux et options de visibilité, voir examples/mutations.md.
Modèle 7 : Écouteurs en Temps Réel
Abonnez-vous aux modifications de documents avec client.listen(). L'écouteur utilise uniquement la partie filtre de GROQ — les projections et les ordres sont ignorés.
const subscription = client.listen(`*[_type == "post"]`).subscribe({
next: (update) => {
/* update.transition: 'update' | 'appear' | 'disappear' */
},
error: (err) => console.error(err),
});
subscription.unsubscribe(); // Nettoyage terminé
Pour les frontends de production, évaluez la nouvelle API Live Content comme alternative plus simple. Pour les options de l'écouteur et les mises en garde, voir examples/mutations.md.
Modèle 8 : TypeGen pour des Requêtes GROQ Typées
Configurez TypeGen dans sanity.cli.ts avec overloadClientMethods: true pour des résultats client.fetch typés. Utilisez defineQuery() de "groq" pour rendre les requêtes découvrables par TypeGen.
// sanity.cli.ts — définir typegen.overloadClientMethods: true
// queries/post-queries.ts — encapsuler les requêtes avec defineQuery()
// sanity.types.ts — types de résultats générés automatiquement
const posts = await client.fetch(allPostsQuery); // Résultat typé
Les chaînes de requête en ligne sans defineQuery() produisent des résultats non typés (any). Pour la configuration complète de TypeGen et le flux de travail, voir examples/core.md.
<decision_framework>
Cadre de Décision
useCdn : true vs false
Les données sont-elles publiques et non personnalisées ?
├─ OUI → useCdn: true (mis en cache en périphérie, rapide)
└─ NON →
├─ Utilisation d'un jeton pour des lectures authentifiées ? → useCdn: false
├─ Besoin de données fraîches en temps réel (aperçu) ? → useCdn: false
└─ Réalisation de mutations ? → useCdn: false
Gestion des Brouillons
Avez-vous besoin de documents brouillons ?
├─ OUI → Utiliser perspective: 'previewDrafts' (nécessite un jeton)
├─ NON → Utiliser perspective: 'published' (par défaut depuis API v2025-02-19)
└─ Mixte (bascule du mode aperçu) ?
└─ Créer deux clients : un public (useCdn: true), un aperçu (jeton + useCdn: false)
Forme de Retour des Requêtes GROQ
Combien de documents attendez-vous ?
├─ Un (par ID, slug, singleton) → Ajouter [0] à la fin (retourne un objet ou null)
├─ Plusieurs (liste, flux) → Pas de suffixe de découpage (retourne un tableau)
└─ Paginé → Ajouter un découpage [start...end]
Gestion des Images
Comment les images doivent-elles être livrées ?
├─ Taille fixe (miniatures, avatars) → urlFor(img).width(W).height(H).url()
├─ Responsive (images d'articles) → srcSet avec plusieurs largeurs
├─ Optimisation du format → .auto('format') pour WebP/AVIF
└─ Recadré à un rapport d'aspect → .width(W).height(H).fit('crop')
Sélection de la Méthode de Mutation
De quelle opération avez-vous besoin ?
├─ Créer un nouveau document → client.create()
├─ Créer ou remplacer complètement → client.createOrReplace() (pour les singletons)
├─ Créer uniquement si manquant → client.createIfNotExists()
├─ Mettre à jour des champs spécifiques → client.patch(id).set({...}).commit()
├─ Supprimer des champs → client.patch(id).unset([...]).commit()
├─ Modifications multiples liées → client.transaction()...commit()
└─ Supprimer un document → client.delete(id)
</decision_framework>
<red_flags>
DRAPEAUX ROUGES
Problèmes de Haute Priorité :
apiVersionmanquant sur le client — OmettreapiVersionutilise un comportement d'API hérité qui peut changer sans préavis. Épinglez toujours à une chaîne de date.- Interpolation de chaînes dans les requêtes GROQ — Interpoler des entrées utilisateur dans les chaînes GROQ permet une injection GROQ. Utilisez toujours les paramètres
$param. - Utilisation de
useCdn: trueavec un jeton — Les réponses mises en cache par le CDN ignorent les jetons d'authentification. Les requêtes authentifiées doivent utiliseruseCdn: false. - Accès aux documents brouillons sans jeton — Les brouillons (documents
drafts.*) nécessitent un jeton API etperspective: 'previewDrafts'. Sans jeton, les brouillons sont invisibles.
Problèmes de Priorité Moyenne :
- Récupération de tous les champs avec
{...}quand seuls quelques-uns sont nécessaires — La sur-récupération gaspille de la bande passante et l'efficacité du cache CDN. Projetez uniquement les champs dont vous avez besoin. .commit()manquant sur les correctifs —client.patch(id).set({...})sans.commit()ne fait rien — la mutation n'est jamais envoyée.- Ne pas utiliser
defineQuery()pour les requêtes GROQ — TypeGen ne peut pas générer de types pour les requêtes qui ne sont pas encapsulées dansdefineQuery()ou assignées à des variables nommées. - ID de projet ou jeu de données codés en dur — Utilisez des variables d'environnement ; les valeurs codées en dur empêchent le changement d'environnement et divulguent les détails du projet.
- Utilisation de
@sanity/block-content-to-reactobsolète — Remplacé par@portabletext/react. L'ancien package n'est plus maintenu.
Erreurs Courantes :
- Oubli de
_keysur les éléments de tableau dans les mutations — Chaque élément d'un tableau Sanity doit avoir un champ_keyunique. Les mutations sans_keyéchoueront. - Utilisation de
_idavecclient.create()—create()génère un_idaléatoire. Si vous spécifiez_idet que le document existe, cela génère une erreur. UtilisezcreateOrReplace()oucreateIfNotExists()pour les opérations idempotentes. - Ne pas gérer le cas où
[0]retournenull— Une requête GROQ se terminant par[0]peut retournernullsi aucun document ne correspond. Vérifiez toujours le résultat avant d'accéder aux propriétés. - Confusion entre
slug.currentetslug— Les slugs Sanity sont des objets avec un champcurrent. Filtrez toujours surslug.current, pas surslugdirectement. - Utilisation de références non incluses (
author->) dans les projections pour la sérialisation — GROQ peut joindre des références dans une requête, mais elles ne sont pas chargées dynamiquement. Utilisez->dans la projection pour déréférencer les références au moment de la requête.
</red_flags>