Claude Code et Contentful CMS : guide d'intégration pratique

Commencer par le périmètre d’intégration

Contentful est un CMS headless : les équipes éditoriales gèrent des contenus structurés dans Contentful, puis le site les affiche via des APIs. Ce découplage est très pratique pour un blog, une documentation, une page produit ou un site multilingue. Claude Code peut accélérer la mise en place, mais seulement si le périmètre est clair.

La demande “branche Contentful” est trop vague. Elle donne souvent une démo qui affiche une entrée publiée, mais qui casse dès que l’on veut prévisualiser un brouillon, afficher la version fr-FR, publier une image, ou invalider le cache d’une page Next.js. Une vraie intégration doit séparer Content Delivery API, Content Preview API, Content Management API, variables d’environnement, locales, types, SSG, ISR et webhooks.

Pour l’architecture de blog CMS, consultez Claude Code blog CMS. Si le contenu CMS doit aussi nourrir une API produit, lisez Claude Code API development. Pour relier contenu et conversion, content funnel audit complète bien ce sujet.

Séparer Delivery, Preview et Management

Les APIs Contentful ont des responsabilités différentes. Les mélanger rend le code plus fragile et augmente le risque d’exposition de secrets.

API	Rôle	Token	Où l’utiliser
Content Delivery API	Lire les contenus publiés	Delivery token	SSG, ISR, Server Components, builds Astro
Content Preview API	Lire les brouillons et modifications non publiées	Preview token	routes de preview côté serveur
Content Management API	Créer les modèles, modifier les entries, publier	Management token ou PAT	scripts locaux et CI de confiance
Images API	Transformer les assets	contexte delivery/preview	helpers d’image, miniatures, OGP

La documentation officielle du SDK JavaScript montre le schéma de preview : preview access token et host: "preview.contentful.com". Les Personal Access Tokens de la Management API sont liés aux permissions utilisateur et doivent être protégés. Gardez ces références sous la main : Contentful JavaScript SDK, Personal Access Tokens, environment permissions et le guide Astro Contentful.

Donner un prompt exploitable à Claude Code

Un bon prompt indique les APIs, les fichiers, les locales et les vérifications. Cela réduit les décisions implicites.

Ajoute une intégration de blog Contentful dans ce dépôt.
- Le contenu publié utilise uniquement Content Delivery API.
- Le mode preview utilise uniquement Content Preview API.
- Content Management API token est limité à scripts/setup-contentful-model.ts.
- La locale par défaut est fr-FR, avec en-US en paramètre.
- Next.js utilise Draft Mode et revalidatePath pour les webhooks.
- Astro lit les entries dans getStaticPaths au build.
- Aucun Preview token ni Management token ne doit partir au navigateur.
- Termine par la liste des fichiers modifiés et des commandes de vérification.

Avec ce contrat, le diff devient lisible. Si Claude Code met CONTENTFUL_PREVIEW_TOKEN dans un composant client, l’erreur saute aux yeux. S’il garde cdn.contentful.com en preview, le contrat le contredit. S’il oublie la locale, la revue le voit avant la mise en production.

Modéliser selon les cas d’usage

Contentful est plus utile quand le contenu est structuré. Tout mettre dans un champ Rich Text permet d’aller vite, mais rend les CTA, la traduction, la recherche et l’analyse plus difficiles.

Cas d’usage	Champs utiles	Cache	Objectif
Blog technique	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + webhook de publication	PDF gratuit, articles liés, formation
Page produit	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	ISR court ou revalidation manuelle	achat, démo, demande de conseil
Documentation	category, version, body, relatedDocs, updatedAt	SSG et synchronisation de recherche	support payant, modèles
Actualités localisées	title/body par locale, region, canonicalSlug	builds par locale	CTA régionaux et leads locaux

Dans un essai, l’erreur a été de mettre articles de blog et pages produit dans le même type blogPost. L’article s’affichait, mais la page produit avait besoin de prix, FAQ, CTA et libellés d’expérimentation. Les éditeurs ont fini par placer des boutons dans le texte riche, ce qui a compliqué le suivi des clics. Claude Code peut corriger après coup, mais il vaut mieux donner un bon modèle dès le départ.

Variables d’environnement et locales

Commencez par un .env.example. Il sert de documentation exécutable pour Claude Code et pour l’équipe.

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=fr-FR
CONTENTFUL_DELIVERY_TOKEN=delivery_token_for_published_content
CONTENTFUL_PREVIEW_TOKEN=preview_token_for_drafts
CONTENTFUL_MANAGEMENT_TOKEN=management_token_for_scripts
CONTENTFUL_PREVIEW_SECRET=random_secret_for_draft_mode
CONTENTFUL_REVALIDATE_SECRET=random_secret_for_webhooks
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Ne placez jamais Preview token ou Management token derrière NEXT_PUBLIC_. Dans Next.js, ce préfixe peut exposer la variable au navigateur. Le token de preview lit les contenus non publiés. Le token de management peut modifier l’espace. Ils doivent rester côté serveur, dans des scripts locaux ou dans une CI contrôlée.

Les environments et les locales sont aussi des sources d’erreurs. Beaucoup d’exemples utilisent master, mais une équipe peut utiliser production, staging ou un alias. Un token autorisé sur master peut renvoyer 403 ailleurs. Côté langues, fr-FR, fr-CA ou une convention interne peuvent coexister. Les fonctions de lecture doivent toujours accepter locale.

Créer un client Contentful typé

La sélection du host et du token doit vivre dans une seule fonction. Le reste de l’application demande seulement une locale et un état preview.

// src/lib/contentful.ts
import { createClient, type EntryFieldTypes, type EntrySkeletonType } from "contentful";

type BlogPostFields = {
  title: EntryFieldTypes.Symbol;
  slug: EntryFieldTypes.Symbol;
  excerpt: EntryFieldTypes.Text;
  body: EntryFieldTypes.RichText;
  heroImage: EntryFieldTypes.AssetLink;
  tags: EntryFieldTypes.Array<EntryFieldTypes.Symbol>;
  publishedAt: EntryFieldTypes.Date;
};

export type BlogPostSkeleton = EntrySkeletonType<BlogPostFields, "blogPost">;

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

export function getContentfulClient(options: { preview?: boolean } = {}) {
  const preview = options.preview ?? false;

  return createClient({
    space: required("CONTENTFUL_SPACE_ID"),
    environment: process.env.CONTENTFUL_ENVIRONMENT ?? "master",
    accessToken: preview
      ? required("CONTENTFUL_PREVIEW_TOKEN")
      : required("CONTENTFUL_DELIVERY_TOKEN"),
    host: preview ? "preview.contentful.com" : "cdn.contentful.com",
  });
}

export async function getBlogPostBySlug(
  slug: string,
  options: { locale?: string; preview?: boolean } = {},
) {
  const locale = options.locale ?? process.env.CONTENTFUL_DEFAULT_LOCALE ?? "fr-FR";
  const response = await getContentfulClient(options).getEntries<BlogPostSkeleton>({
    content_type: "blogPost",
    "fields.slug": slug,
    limit: 1,
    include: 2,
    locale,
  });

  return response.items[0] ?? null;
}

Quand le modèle s’étoffe, générez les types depuis Contentful et faites échouer la CI en cas de divergence. Même avec une génération automatique, conservez la règle : IDs de modèle, field IDs, locale et preview doivent être explicites.

Next.js et Astro : choisir la bonne stratégie

Next.js convient bien aux pages qui nécessitent preview et revalidation à la demande. Les pages publiques peuvent être statiques, les brouillons peuvent utiliser Draft Mode avec Preview API, et un webhook Contentful peut appeler une route qui lance revalidatePath. Vérifiez toujours la version actuelle de draftMode et revalidatePath, car les exemples copiés d’anciennes versions peuvent être trompeurs.

Astro est excellent pour un rendu statique prévisible. On lit les entries dans getStaticPaths, puis on génère le HTML au build. En revanche, une modification Contentful ne change pas automatiquement le HTML déjà déployé. Il faut déclencher un rebuild via webhook, ou garder les pages à forte fréquence de modification dans Next.js. Pour un blog et une documentation, Astro SSG est souvent parfait. Pour une landing modifiée chaque jour, ISR est plus souple.

Pièges à vérifier avant publication

Problème	Symptôme	Correction
Preview token envoyé au host Delivery	401 ou brouillon invisible	utiliser preview.contentful.com
Delivery token utilisé en preview	page null	passer par Content Preview API
Management token exposé	fuite critique	limiter aux scripts et CI
Locale oubliée	mauvaise langue ou champs vides	passer locale à chaque requête
Asset non publié	texte visible, image absente	publier entry et asset
Webhook sur chaque sauvegarde	cache production vidé trop souvent	écouter publish/unpublish
Field ID renommé	types et rendu cassés	conserver les API identifiers

La vérification finale doit inclure un build proche de la production, pas seulement le serveur de développement. Demandez à Claude Code de lister, pour chaque route importante, le token, le host, la locale et le path utilisés. Cette petite table révèle souvent les erreurs de configuration.

Relier le CMS à la monétisation

Une intégration CMS doit soutenir le parcours business. Ajoutez des champs structurés comme ctaKind, ctaLabel, ctaUrl et relatedPosts au lieu de cacher tous les CTA dans le Rich Text. Un tutoriel technique peut pointer vers un cheatsheet gratuit, un article d’adoption d’équipe vers training and consultation, et un contenu de modèles vers products.

Cette structure permet de suivre cta_click avec un identifiant stable et de laisser les éditeurs changer le texte sans casser les composants. Lors du test de cette configuration, le gain le plus net venait de la séparation initiale entre Delivery, Preview et Management. Les diffs générés par Claude Code étaient plus courts, les erreurs de locale plus visibles et les problèmes de preview plus faciles à corriger avant le déploiement.