La logique headless ne se limite pas à déplacer le contenu hors du front-end : elle transforme la manière dont les données sont interrogées, structurées et exploitées. Avec Sanity, l’accès au contenu passe par un langage de requête spécifique, GROQ. Cette approche m’a confronté à une réalité simple mais profonde : le front-end ne doit plus s’adapter à une API, c’est la requête qui doit être conçue pour produire exactement ce dont l’interface a besoin. Ce changement de perspective a constitué l’un des moments les plus marquants de la construction du projet.

GROQ : un langage qui change la relation au contenu

Au début, GROQ m’a donné l’impression d’être un langage “à part”, moins intuitif que les paradigmes REST ou GraphQL que j’avais l’habitude d’utiliser. L’absence d’endpoints préétablis est d’abord déroutante : on se retrouve face à une forme de liberté qui exige une rigueur nouvelle. Ce décalage m’a forcé à réfléchir autrement, non plus en termes de ressources, mais en termes de données à produire.

GROQ n’est pas un simple outil d’accès aux données : il est un outil de composition. Le fait de pouvoir définir précisément la structure des résultats dans la requête-même rend la logique de récupération plus proche de l’interface. À mesure que l’on progresse, cette proximité devient un avantage, car elle réduit les transformations nécessaires côté front-end.

Requêter selon les besoins du front-end (et non selon une API)

L’un des changements les plus marquants a été la façon de penser les requêtes. Plutôt que de récupérer un objet “article” complet, puis de le filtrer et de le transformer dans le code, GROQ permet de demander uniquement ce qui est utile.

*[_type == "article"]{
  title,
  slug,
  publishedAt
}

Cette requête illustre un principe simple mais essentiel : la requête est conçue en fonction du besoin du front-end (ici, une liste d’articles), et non en fonction d’un endpoint général. Cette logique a eu un impact direct sur la manière dont j’ai structuré les pages, en favorisant des flux de données plus sobres et plus rapides.

Relations et projections : le cœur du modèle headless

GROQ s’avère particulièrement intéressant lorsque l’on travaille avec des relations. Les références entre contenus, définies lors de la phase de modélisation, peuvent être exploitées directement dans la requête, ce qui permet de produire un résultat cohérent sans multiplier les appels.

*[_type == "article"]{
  title,
  author->{
    name,
    role
  }
}

Cette capacité à “suivre” une relation dans une même requête est un point que j’ai trouvé particulièrement puissant. Elle renforce la cohérence des données et réduit la complexité du front-end. Mais elle révèle aussi une limite : si la modélisation est imparfaite, les requêtes deviennent rapidement lourdes ou peu lisibles. Cela met en évidence une réalité importante : GROQ ne remplace pas une bonne architecture de contenu, il la met au contraire en lumière.

Performance et sobriété : la requête comme levier

Une autre dimension importante de GROQ est la maîtrise de la performance. Dans un projet headless, la quantité de données transférées peut devenir un enjeu majeur. La capacité à limiter, trier et structurer les résultats directement dans la requête est donc un atout non négligeable.

*[_type == "article" && defined(publishedAt)]
  | order(publishedAt desc)[0...5]{
    title,
    excerpt
}

Ce type de requête m’a poussé à penser la performance dès la conception. Plutôt que d’optimiser uniquement côté front-end, la performance devient une dimension de la requête elle-même. Cette logique s’accorde avec les mécanismes de génération statique de Next.js, qui seront abordés dans l’article suivant.

Courbe d’apprentissage : ce que j’ai vraiment retenu

L’apprentissage de GROQ a été moins une question de syntaxe que de posture. Au début, j’ai eu tendance à chercher des équivalents REST ou GraphQL, comme si je devais “traduire” mentalement mes requêtes. Cela m’a souvent conduit à écrire des requêtes trop larges, puis à corriger après coup. Ce processus était frustrant, mais il m’a aussi appris quelque chose de précieux : il faut penser la requête avant de penser l’interface.

À mesure que la pratique s’est installée, j’ai constaté que GROQ impose une discipline bénéfique. Il devient difficile de travailler avec un contenu mal modélisé, car la requête met immédiatement en évidence les incohérences. En ce sens, GROQ agit comme un révélateur de la qualité de la structure des données. Cette observation renforce l’idée que la modélisation n’est pas une étape initiale isolée, mais une composante permanente de l’architecture.

GROQ ne se limite pas à un langage de requête : il structure la manière dont les données sont pensées, récupérées et exploitées. En rapprochant la requête du besoin réel du front-end, il encourage une approche plus cohérente, plus sobre et plus lisible de l’accès aux données. Cette approche a été, pour moi, un tournant dans la compréhension du headless : la donnée cesse d’être une ressource à consommer et devient un élément à composer.