Communitygithub.com

agents-inc/skills

Plateforme de contenu structuré — requêtes GROQ, définitions de schémas, @sanity/client, Portable Text, gestion d'images, écouteurs en temps réel, mutations, TypeGen

Qu'est-ce que skills ?

Cette compétence fournit un ensemble complet de modèles et de bonnes pratiques pour travailler avec Sanity, une plateforme de contenu structuré. Elle couvre la configuration du client avec `@sanity/client`, l'écriture de requêtes GROQ paramétrées et sécurisées, la définition de schémas typés avec `defineType`/`defineField`, le rendu de contenu riche via `@portabletext/react`, la génération d'URL d'images optimisées avec `@sanity/image-url`, et la réalisation de mutations (création, mise à jour, suppression). La compétence met l'accent sur la gestion explicite des brouillons, l'utilisation de `useCdn` selon le contexte, et la génération de types TypeScript avec Sanity TypeGen. Elle est conçue pour les développeurs utilisant Sanity avec React, Next.js, ou tout framework frontend, et fournit des exemples concrets dans des fichiers séparés (core.md, schemas.md, rich-content.md, mutations.md).

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-cms-sanity

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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/client pour la récupération de données. Définissez toujours apiVersion sur une chaîne datée, utilisez useCdn: true pour les lectures publiques, gérez les documents brouillons explicitement, utilisez @sanity/image-url pour les transformations d'images, et rendez le texte enrichi avec @portabletext/react. Générez les types TypeScript avec sanity 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/client avec createClient pour 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 createClient et configuration de apiVersion
  • 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 :

Mutations & 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 :

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Mise en cache CDN — Les requêtes de lecture publiques utilisent useCdn: true pour des réponses mises en cache en périphérie. Les mutations et les lectures authentifiées utilisent useCdn: false pour des données fraîches.
  6. 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é :

  • apiVersion manquant sur le client — Omettre apiVersion utilise 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: true avec un jeton — Les réponses mises en cache par le CDN ignorent les jetons d'authentification. Les requêtes authentifiées doivent utiliser useCdn: false.
  • Accès aux documents brouillons sans jeton — Les brouillons (documents drafts.*) nécessitent un jeton API et perspective: '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 dans defineQuery() 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-react obsolète — Remplacé par @portabletext/react. L'ancien package n'est plus maintenu.

Erreurs Courantes :

  • Oubli de _key sur les éléments de tableau dans les mutations — Chaque élément d'un tableau Sanity doit avoir un champ _key unique. Les mutations sans _key échoueront.
  • Utilisation de _id avec client.create() — create() génère un _id aléatoire. Si vous spécifiez _id et que le document existe, cela génère une erreur. Utilisez createOrReplace() ou createIfNotExists() pour les opérations idempotentes.
  • Ne pas gérer le cas où [0] retourne null — Une requête GROQ se terminant par [0] peut retourner null si aucun document ne correspond. Vérifiez toujours le résultat avant d'accéder aux propriétés.
  • Confusion entre slug.current et slug — Les slugs Sanity sont des objets avec un champ current. Filtrez toujours sur slug.current, pas sur slug directement.
  • 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>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills associés